• VMware Horizon Sync Scripts

    ControlUp is committed to ensuring you - the ControlUp user - have the best system monitoring experience possible. We understand the importance of reflecting changes in your VMware Horizon environment in the ControlUp Console. Therefore we have developed synchronization scripts that let you automatically reflect those changes in the ControlUp Real-Time Console.

    Prerequisites

    To use our synchronization scripts, there are some prerequisites that must be considered. These preconditions are explained in greater detail in the Prerequisites for Running Horizon Sync scripts article. 

     

    Installation Guide

    1. Download the synchronization script Horizon_Sync.ps1 and the Build-CUTree.ps1 from our Github repository. 
    2. Create a Windows Task for running the script automatically on the ControlUp Monitor. Arguments for the Task Scheduler in the Input Parameters section below.
    3. Optionally, create an exceptions file. This provides the option to exclude machines, pools, or RDS farms from being synchronized with the CU Console. 

    Input Parameters

    Name Description Format Mandatory
    HVConnectionServerFQDN
    Fully Qualified Domain Name of the Horizon connection server String Yes
    folderPath
    Path of the folder where all objects in the ControlUp organization tree are placed. String Yes
    Exceptionsfile
    Path of the exceptions file that defines DNS names for machines that you don’t want to add to the ControlUp organizational tree. String No
    Preview Shows expected results without committing any changes to the ControlUp environment (works like the -WhatIf switch in PowerShell). Switch No
    Delete Enables the script to execute the removal of objects. Switch No
    LogFile Log script output to a text file. Can be used with the Preview parameter to log uncommitted changes. Switch No
    Site Name of the Monitor site where machines are added to. String No
    batchCreateFolders
    Create folders in batches rather than sequentially. Switch No
    LocalHVPodOnly
    Used for synchronization of the local Horizon Site only. Switch No
    force Force folder creation if number exceeds safe limit Switch No
    SmtpServer
    SMTP server to send alert emails from
    String No
    emailFrom
    Email address to send alert email from
    String No
    emailTo
    Email addresses to send alert email to
    String Array No
    emailUseSSL
    Use SSL to send email alert
    Switch No


    Use Case

    Our VMware Horizon environment contains different Desktop Pools, as shown below. Our goal for this use case is to hide the ek_test_pool folder from the CU Console view.

    mceclip1.png

    Note: The screenshot above shows the desktop pools that are maintained on the specific server. The script does not add / remove folders from the EUC Environments folder as this read-only!

    The desktop pools in our CU Console tree are located in different folders:

    mceclip8.png

    The next step is to find out, which monitor is responsible for our data collection.

    mceclip2.png

    Once you identified the monitor, connect remotely to this machine and create the Windows Task as explained in this article. For our use case we will use the following arguments:

    -ExecutionPolicy RemoteSigned -NoLogo -File "C:\CU Environment Sync Scripts\Horizon_Sync.ps1" -folderPath "controlup demo\IL Datacenter\Virtual Desktops\Horizon Demo"  -HVConnectionServerFQDN "cuview71connect.controlup.demo" -logfile "C:\CU Environment Sync Scripts\Horizon Sync.log" -Exceptionsfile "C:\CU Environment Sync Scripts\demo_exceptions.txt"

    The demo_exceptions.txt that is used in the argument consists of several folders, for example, the ek_test_pool

    mceclip9.png

    The script checks all folders that are found in the provided folderpath parameter, in our case controlup demo\IL Datacenter\Virtual Desktops\Horizon Demo, and excludes all folder names that are saved in the demo_exceptions.txt file.

    Run the task in the Task Scheduler manually or wait for the automated schedule. Once completed, the ek_test_pool is not shown anymore in our CU Console tree. 

    mceclip10.png

     

     

  • Prerequisites for Running Horizon On-Premises Sync Scripts

    Before you can use our synchronization scripts to update the ControlUp organization tree with your Horizon on-prem updates, you need to review the prerequisites below.

    For information on the sync script itself, see VMware Horizon Sync Scripts.

    If you are running Horizon on Azure, see Horizon on Azure Sync to ControlUp.

    Prerequisites

    To run any of our Horizon scripts, you have to first:

    • Create a credentials file for automated authentication to the Connection Server.
    • Install and configure the VMware PowerCLI.
    • Install the Hv.Helper module (not required by all scripts, but recommended to install).

    Create Credentials File

    Running our Horizon View scripts requires authentication to the Horizon View Connection Server. Connecting to a connection server doesn’t use standard pass-through authentication from Active Directory, so you must explicitly pass credentials. We have created a script that creates a credentials file on the ControlUp monitor machine from where these scripts must be run. Our scripts use this credentials file for automatically passing the user credential to the connection server authentication. 

    Note: PSCredentials Objects can only be used by the user that created the object on a specific machine. This means that the user that creates the credentials file must have a user profile on this machine.

    To create the credentials file:

    1. Open the ControlUp console and click Script Actions. The Script Management screen appears.

      mceclip21.png

    2. From the Scripts Management screen, type Create credentials for Horizon scripts (1) in the search box and then click Add Script (2).

      Pic12.jpg

    3. Check the box to accept the terms (1), and click Next (2) to continue to the next screen for creating user permissions.

      Pic14.jpg

    4. Grant permissions to user groups that should be able to run the script. Click Add Action to save the settings.

      Pic15.jpg
      After the script is installed, it will appear under the Organization Scripts tab. 

      mceclip0.png

    5. From the ControlUp Console grid, locate the monitor machine where you want the credentials file to be stored. Right-click the machine (1) and type Create in the search box (2). Select the Create credentials for Horizon scripts (3) that you just added and a new prompt appears.

      Pic18.jpg

    6. From the Credentials section, select a user that is allowed to run scripts on the monitor machine. This is the user that appears in the XML file name. 

      In the Command Line Arguments, enter the user credentials for the user that needs to connect to the Horizon Connection Server. The format must be domain\username. This is the user, for which the PSCredential object is created. 

      Pic20.jpg

    7. Click OK. The Action Results Screen appears.
    8. In the Output tab, check that the credentials file was created. The message PSCredential object created and stored in C:\ProgramData\ControlUp\ScriptSupport indicates a successful creation of the file.

      Pic21_1.jpg

      When you open the XML file, you see that the password is encrypted. 

      Pic23.jpg

     

    Install and Configure VMware PowerCLI

    The VMWare PowerCLI is a feature-rich collection of Powershell modules for interacting with your VMware environment. As our VMware scripts use PowerCLI, it is necessary to have it installed on the machine that runs the scripts (usually the ControlUp Console or the ControlUp Monitor).

    There are many ways to get the VMware PowerCLI installed on your machine. In this article, we will explain how to install the PowerCLI from the ControlUp Console.

    To install VMware PowerCLI:

    1. In the CU Console, right-click the machine where you want to install the PowerCLI. In the Search Box type PowerCLI (1). Select Script Actions (2) > More… (3) > Install VMWare PowerCLI (4).

      Pic24.jpg
    2. Under CEIP Configuration, set True or False, depending on if you want to send data to the VMware Customer Experience Improvement Program (CEIP). By default, PowerCLI stops working when certificates are not signed properly. You can set 3 different values:

      Warn: Shows a warning saying that the certificate is not valid and provides further information about reasons for not considering the certificate. 

      Ignore: A connection is established, ignoring the invalid certificate
      Fail: No connection is established if the certificate is not valid

      Pic29.jpg

    Installing Hv.Helper Module

    Some of our Horizon View scripts use the Hv.Helper Powershell module. Although not all of our scripts require this module, it is recommended to install this module on every machine that is running the ControlUp Console or/and ControlUp Monitor.

    Note: Installing this module on your Horizon View VMs is not necessary.

     

    To install the Hv.Helper module:

    1. Right-click the machine where you want the Horizon View scripts to run. In the search box type Hv. Hover over Script Actions (2) > More... (3) > Install Hv.Helper module for Horizon View scripts (4).

      mceclip0.png

    2. By default, the script installs the Hv.Helper module only if it does not exist on the target machine. This behavior is set with the False flag, as shown below. If you want to overwrite an already installed module, set the flag to True.

      mceclip1.png

      Alternatively, you can install the Hv.Helper module by following the instructions given in this Github repository
  • Active Directory Organizational Unit Sync with ControlUp Console Tree

    You can synchronize the Organizational Unit's (OU) structure of an Active Directory (AD) domain to the Organization Tree in the ControlUp Console. This is especially useful when your environment is constantly changing, for example when workstations are added and removed. Use this AD sync script to synchronizes any changes in a specific OU to the ControlUp Console. A Windows Scheduled Task on the ControlUp monitor machine is used to automate the synchronization process in the background.  

    Installation Guide 

    1. Download the AD_Sync.ps1 and Build_CUTree.ps1 scripts from our Github repository.
    2. Copy both scripts onto the machine where the ControlUp monitor is installed. They have to be in the same directory.
    3. Create a Task Scheduler by following the instructions in this article.

    AD Sync Script Description

    The table below describes all input parameters that can be used to call the script. To use the script, you need to provide at least 2 input parameters (OU, folderPath) as described in this table. 

    Input Parameters

    Name Description Format Mandatory
    OU The distinguished name of the Organizational Unit (OU). String Yes
    folderPath Folders into which the AD structure is imported in the ControlUp organizational tree. String Yes
    domain The AD domain containing the OU - if it's not the current domain as specified in the OU parameter. String No
    Preview Shows expected results without committing any changes to the ControlUp environment (works like the -WhatIf switch in PowerShell). Switch No
    Delete Enables the script to execute the removal of objects. Switch No
    LogFile Log script output to a text file. Can be used with the Preview parameter to log uncommitted changes.  Switch No
    Site Name of the Monitor site to where machines are added. String No
    batchCreateFolders Create folders in batches rather than sequentially. Switch No
    force Force the folder creation if the number of new folders is too large. Switch No

    Use Case

    Our goal is to reflect the workstations under the OU Workstations_Marketing in the ControlUp Console. 

    mceclip1.png

    1. Download the AD_Sync.ps1 and Build_CUTree.ps1 scripts from our Github repository.
      The best way to download scripts from Github is to click the Raw button and then copy & paste the scripts to the local computer. 

      mceclip0.png

    2. Save both scripts in the C:\temp directory on the Monitor machine. 

      mceclip3.png

    3. Create a Windows Task Schedule as described here. 
      Use these arguments as input parameters for the script:
      C:\temp\AD_Sync.ps1 -OU 'OU=Workstations_Marketing,OU=Marketing,DC=bendomain,DC=local' -folderpath 'ParentFolder'

      Tip: You can always test the AD_Sync script without using a Task Scheduler. To do so, open Powershell as an administrator and execute the command below:

      Import-Module "C:\Program Files\Smart-X\ControlUpMonitor\Version [X.X.X.XXX]\ControlUp.PowerShell.User.dll"
      .\AD_Sync.ps1 -OU "OU=Workstations_Marketing,OU=Marketing,DC=bendomain,DC=local" -folderPath 'ParentFolder' -ErrorAction SilentlyContinue

      mceclip8.png
      The script looks for the OU "Workstations_Marketing" in the bendomain.local domain and add its objects to a "ParentFolder" folder in the ControlUp Console.

    4. Run the task that you created. Right-click the task and select Run.

      mceclip4.png
    5. The ParentFolder that was specified as an input parameter is shown in the ControlUp Console. 

      mceclip6.png

    Using the -Site Parameter

    This use case shows how to use the script to add OU objects to a dedicated ControlUp Monitor site. This is done by using the -Site switch.

    Use the following arguments to call the script:

    .\AD_Sync.ps1 -OU "OU=Workstations_Marketing,OU=Marketing,DC=bendomain,DC=local" -folderPath ParentFolder1 -Site "Default2"

    This adds both workstations to the Default2 monitor site. 

    mceclip1.png

    Note: If the site parameter is not specified, the script automatically uses the Default site.

    -LogFile Parameter

    This parameter provides a logging functionality. The script output is logged to a text file that you specify in the parameter. 

    .\AD_Sync.ps1 -OU "OU=Workstations_Marketing,OU=Marketing,DC=bendomain,DC=local" -folderPath ParentFolder1 -LogFile ".\LogFileWithChanges.txt"

    This command creates a new log file "LogFileText.txt" and commits changes to the ControlUp Console. 

    mceclip5.png

    -Preview Parameter

    The Preview parameter is used for test purposes. It's highly recommended to use this parameter when you don't want to commit any changes to the ControlUp console.

    .\AD_Sync.ps1 -OU "OU=Workstations_Marketing,OU=Marketing,DC=bendomain,DC=local" -folderPath ParentFolder1 -LogFile ".\LogFileTest.txt" -Preview

    The log file displays "Preview Mode", indicating that no changes were committed to the ControlUp console. 


    mceclip6.png

  • Auto-Sync Environment Changes into ControlUp's Organizational Tree

    You can automatically keep the ControlUp organizational tree up-to-date with the ongoing changes in your environment topology. Our synchronization scripts are run automatically as a Windows scheduled task to read your topology and update ControlUp with added or removed machines. Those changes are automatically reflected in the ControlUp organizational tree and don't have to be made manually. You can continuously monitor the actual machines in your environment and remediate any issues, saving you time and resources. 

    • Our sync scripts are written in PowerShell and stored in our GitHub repository.
    • Depending on your VDI, you may have to run special credentials scripts to enable running the sync scripts. These are detailed in the articles covering each environment.
    • You set the Windows scheduled task to automatically run the sync script on the ControlUp monitor machine. This procedure is detailed below.

    Environments

    The following is a list of available types of scripts to synchronize your environment. Click an environment to see further information and instructions on each. 

    VMware Horizon Sync Scripts

    VMware Horizon on Azure Cloud Sync Scripts

    Microsoft WVD

    Citrix Virtual Apps and Desktops on-premises (CVAD or XenDesktop)

    Active Directory Organizational Unit

    Citrix Cloud (early stages of development)

    Prerequisites for every sync script

    • The sync has to be performed on a machine that has the ControlUp Monitor component installed. This is because the monitor is the component that communicates with the console 24/7. You can read about Adding a ControlUp Monitor.
    • The user has to have ControlUp admin privileges on the ControlUp monitor machine.
    • The monitor machine must have access to credentials to read the changes in the target environment. 
    • Powershell version 5.x must be installed on the Monitor machine. 

    Schedule a Windows Task on the ControlUp Monitor

    To enable these scripts to continuously update the ControlUp organizational tree, you create a Windows Scheduled Task on the ControlUp monitor machine to periodically run the scripts.

    To set up a Windows Task:

    1. Open the Windows Task Scheduler. Press WIN + R and type taskschd.msc

      taskschm.jpg

    2. In the Task Scheduler window, click the Task Scheduler Library and select Create Task in the Action pane as seen below. The Create Task window appears. 

      CreateTask1.png

    3. In the General tab, provide a new name for the task. Under Security options, click Change Users or Group.

      Change2.png
    4. Select the service account used for running the monitor.

      AD2.png

    5. Select the Run whether user is logged on or not radio button.

      SU2.png

    6. Open the Triggers tab and click New. The configuration window for triggers appears. 

      Trigger2.png

    7. From the Begin the task dropdown menu, select On a schedule (1). Click the Daily checkbox (2) and under Recur every, set 1 days (3). Click the Enabled checkbox (4) to automatically enable the trigger after closing this window.  

      Tr2.png

      Note: The settings of the scheduler depend on your organization's requirements. If not specified in the script-specific article, our general recommendation is to run all sync scripts once a day.

    8. In the Create Task window, open the Actions tab and click New
      AA2.png

    9. Under Program/script paste the path of the Powershell executable.  C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
      Additionally, you need to define the script arguments, which can be found in the Input parameter section of the corresponding script. 

      PS23.png
  • Preparation of Horizon Scripts

    Introduction

    ControlUp 8.1 and above has the ability to monitor and manage VMware Horizon.

    ControlUp has created a number of Powershell scripts that can run either manually or automatically. However, some preliminary steps must be taken prior to using these scripts. This article guides you through the environment preparation process to use our Horizon scripts.

    Using Script Based Actions for VMware Horizon

    To use Script Based Actions (SBA’s) for VMware Horizon certain elements must be in place. Every Horizon based SBA user needs a credential file created on the system in use. This includes the monitor if used for automated actions.

    Creating a Credentials File

    To create a credentials file the SBA called ‘Create credentials for Horizon View scripts’ must be invoked.

    To create a credentials file:

    1. Right click the machine that you want to create the credentials on and click Script Actions > More… > Create credentials for Horizon View scripts select the correct SBA, and the > Create credentials for Horizon View scripts popup appears.
      mceclip2.png
    2. From the Credentials section, enter/select the user to be granted to run the scripts.
      mceclip3.png
    3. Create a new username and password and click OK, and the script is executed.
      Note: The username field is in domain/username format.
      mceclip4.png

    VMware PowerCLI Installation and Configuration

    Installing

    VMware PowerCLI can be installed with the Install and Configure VMware PowerCLI SBA. When this SBA is used PowerCLI is installed for all users on the system. This SBA installs PowerCLI from the PowerShell Gallery so that it can be installed manually, if needed.

    To install PowerCLI the latest version of the Nuget package provider is required and is installed by the SBA, as well.

    Configuration

    There are two main configurations that can be set for VMware PowerCLI:

    • Choosing whether you want to join the VMware Customer Experience Improvement Program (CEIP). More information about this program can be found here.
    • What action should be taken if the certificates for your various VMware components are not trusted. By default, PowerCLI will stop working when the certificates are not signed properly so it is recommended to have it set to ‘warn’ to receive a warning or ‘ignore’ to ignore the fact that these certificates haven’t been signed.

    Both configuration items are handled in the Install and Configure VMware PowerCLI SBA as well. To ensure maximum security, by default, the CEIP program is not set. The Invalid Certificate action is set to warn when there are many certificates for Horizon environments in use that have been signed for the URLs that the users connect to and not to the various URLs of the connection servers themselves.

    To install and configure the VMware PowerCLI:

    1. Right click the system where you want to install PowerCLI and select Script Actions > More… > Install and configure VMware PowerCLI, and the Install and configure VMware PowerCLI popup appears.
      mceclip5.png
    2. Select True or False for the CEIP configuration and Warn, Fail or Ignore for Invalid Certificate Action, and click OK and a confirmation screen appears to verify that the configuration is updated.
      mceclip6.png
      Note: This may take a while depending on available resources. You can check how busy the system is by looking at the Powershell process.
      mceclip7.png

    The Hv.Helper Module

    ControlUp’s Horizon scripts use the Hv.Helper Powershell module. This needs to be available on every machine running the ControlUp Console or Monitor and the Horizon scripts.
    As a shortcut, we offer a script that has the module embedded so you can simply install it on the required targets. You do NOT need to have the module installed on your Horizon View VMs.

    To install the Hv.Helper module:

    1. Right click the system where you want to install the Install Hv.Helper Module and select Script Actions > More… > Install Hv.Helper module for Horizon View scripts, and the Install Hv.Helper module for Horizon View scripts popup appears.
      mceclip8.png
    2. By default, existing modules are not overwritten. To overwrite an existing version, change Overwrite existing… to True, and select OK and a confirmation screen appears to verify that the helper module is installed.
      mceclip9.png

    If you prefer to download the Hv.Helper module, you can do so from Github: https://github.com/vmware/PowerCLI-Example-Scripts/tree/master/Modules/VMware.Hv.Helper

    Credentials

    It is important to note that automatic pass-through authentication for your Windows credentials is not possible. Every time a connection is made with the Horizon Connection Server you must explicitly pass credentials. To fix this, ControlUp has come up with a solution using PSCredential objects.

    A PSCredential object can be used to store the credentials for the user by creating the object, and setting to only work on the machine that the object was created on. Horizon View scripts look for a PSCredential object for running the scripts in the %PROGRAMDATA%\ControlUp\ScriptSupport folder. The object itself uses the following naming convention: %USERNAME%_HorizonView_Cred.xml

    To clarify, the object is stored as an encrypted XML file. It can only be decrypted and used by the user that created it on the system where it was created.

    To create this object on all the machines running Horizon scripts ControlUp created the script: Create credentials for Horizon View scripts. This script creates the PSCredential object for you and optionally installs the Vmware.Hv.Helper module as well.

    Using the Create credentials for Horizon View scripts

    Before preparing the machines with the PSCredential Object, you must determine what the PSCredential object is to be used for, because, as mentioned above, the object has a major dependency; it can only be used by the Windows account under which context it was created. If you run the scripts yourself, (manually OR with automation, where the monitor is using YOUR stored credentials), simply open the console and follow the instructions below.

    However, to keep things simple, it is recommended that the monitor uses a dedicated service account. With a service account, you can use an extremely complicated password that can be set to never expire.

    You can also lock down the account so it will only have permission to perform very specific tasks. For example, if you use the service account to run automation scripts for Horizon, this account will not need a mailbox, home drive, etc. Once everything you don’t need is removed, except for the appropriate VMware permission, you can now create a stored credential for this account in the console to be used for the monitors. (https://support.controlup.com/hc/en-us/articles/207203265-Credentials-Store)

    Note: With either approach, the script must run using stored credentials, therefore it is recommended to ensure that you have the set of credentials you want to use in the store before running the script. You can use your own credentials or service account credentials.

    To run the Create credentials for Horizon View scripts:

    1. Open the Scripts pane from the Home tab in the console and find Create credentials for Horizon View scripts. Select the script and download it.
      Note: You can close the Scripts pane while the script is downloading. The download should only take a few minutes.
    2. In the console, select all the machines you wish to be prepared for the Horizon scripts.
    3. Right click and navigate to Scripts > More > Create credentials for Horizon View scripts, and the Create credentials for Horizon View scripts popup appears.
    4. From the Credentials dropdown, select the stored credentials you wish to use and enter the username and password to be used to run the script, click OK and the script runs.
      image002.png
      Note: In this example, the account used to run the script and the account used to authenticate to Horizon are not the same. Therefore, the script is run by the automation account (in this case the ‘general’ service account MyAutomationAccount) but will authenticate to Horizon using the dedicated HorizonViewAccount
      You can also give your automation account the required permissions in Horizon and use this account for Horizon authentication.
      Each approach has its pros and cons: By using two separate accounts you increase security, meaning not making the automation account a very powerful account that has permissions on every system, but maintaining two accounts does increase administration. This works the other way, too, using only one account is less secure but requires less administration.

    When running a Horizon script on these machines the script will look for the PSCredential object in the %PROGRAMDATA%\ControlUp\ScriptSupport folder and use it to authenticate to the Horizon Connection Server.

    Note: If the account password stored in the PSCredential object is changed, you must run the ‘Create…’ script again as the password in the object is no longer valid. This is another example why it’s recommended to have a service account with a very complicated password that never changes.

    As always, if you have any questions, please do not hesitate to reach out to our support team at support@ControlUp.com

  • Horizon on Azure Sync to ControlUp
     

    Using our synchronization scripts, you can automatically populate the ControlUp organizational tree with your Horizon VDI running on the Azure cloud. Our sync script is run as a Windows scheduled task so that when you add or remove machines, those changes are automatically reflected in the organizational tree in ControlUp. You don't have to make any of those changes manually. When the script is run, your ControlUp organization reflects your current Horizon VDI for monitoring and remediation.

    • The sync script is written in PowerShell and stored in our GitHub repository.

    • You must run the credentials script twice for the dual authentication required by Horizon Cloud.
    • You set the Windows scheduled task to run the sync script on the ControlUp monitor machine. 

    Prerequisites

    • The sync has to be performed on a machine that has the ControlUp Monitor component installed. You can read about Adding a ControlUp Monitor.
    • The ControlUp Monitor must be version 8.1.5.600 or higher.
    • The user running the scripts must have a local profile on the ControlUp Monitor machine. Ensure that the same user logs onto the machine at some point before running the scripts.

    1. Access the scripts from our GitHub repository 

    You download the sync scripts from our GitHub repository of environment scripts which also includes synchronization scripts for other environments, including Horizon installed on-premises.

    1. Download the following scripts:
      Store credentials.ps1
      Horizon_Azure_Sync.ps1
      Build-CUTree.ps1 
    2. Copy these scripts to the machine running the ControlUp Monitor. These scrips must reside in the same folder on the Monitor machine.
    3. Optionally, in a PowerShell window, run this command to see the script's parameters, their descriptions, and default values:
        get-help \<path to the file>\Horizon_Azure_Sync.ps1

    Input Parameters

    Here are the parameters in the sync script Horizon_Azure_Sync.ps1. These are the parameters to assign when adding the argument in step 3. Set up a Windows Scheduled Task.

    Name Description
    folderPath *Mandatory. The target folder in the ControlUp organizational tree to save these objects.
    preview Displays the expected results without committing any changes to the ControlUp environment.
    base

    The base of the URL shown after manual logon to the Horizon Azure admin portal.

    For example in this URL: https://cloud-us-2.horizon.vmware.com/horizonadmin, the base would be cloud-us-2.

    delete Enables the script to execute removing objects from the ControlUp organizational tree. Use with the Preview parameter to see the proposed changes before making them.
    logfile Specify a text file to log the output. Can be used for debugging and with the preview parameter to see the proposed changes. Log data is appended to this file with each run of the script.
    site Specify a ControlUp Monitor site to assign the objects. Default value: default
    batchCreateFolders
    Create folders in batches rather than individually
    force
    Force folder creation if number exceeds safe limit
    SmtpServer
    Smtp server to send alert emails from
    emailFrom
    Email address to send alert email from
    emailTo
    Email addresses to send alert email to
    emailUseSSL
    Use SSL to send email alert

    2. Create the credentials files by running the Store_credentials.ps1 script

    The Horizon on Azure Cloud requires dual authentication. To run the scheduled task on the ControlUp Monitor machine, you need both sets of credentials. Therefore you have to run the Store_credentials.ps1 script twice to create those credentials files to access both: 

    • The MyVMware site.
    • The Horizon Cloud Active Directory.
    To create the required credentials files:
    1. Access the ControlUp Monitor machine as the user who will be running the scheduled task.
    2. On the Monitor machine, go to the folder where you saved the Store_credentials.ps1 script.
    3. Run a PowerShell prompt.
    4. Run this command: 
      & '.\store credentials' -credential $null -credentialType HorizonCloudmyVMware
      Note: If you are not in the same folder as where the store_credentials.ps1 script is saved, you must give the full path after the '.'.

    5. When prompted, enter the User name and Password to access the MyVMware site.CredentialPromptMyVMware.jpg
    6. Run this command from the same folder as the script:
      & '.\store credentials' -credential $null -credentialType HorizonCloudDomain
    7. When prompted, enter the User name and Password as the domain\username used to access the Horizon Cloud site.
      CredentialPromptCloudDomain.jpg

    Once you have run the script twice, two encrypted .xml files are created in this folder on the ControlUp Monitor machine: C:\ProgramData\ControlUp\ScriptSupport.

    The names of those encrypted files include the user who ran these scripts and must be the same user to run the scheduled task. The user who ran the scripts and created these encrypted files is admingle.
    CredentialFiles.jpg

    If you are running the scheduled task under a different account, you need to run the script again twice to set up new credentials files as these can be used only by the account that created them on the same machine they were created.

    3. Set up a Windows Scheduled Task

    Follow the steps in this article to create the Windows Scheduled Task.

    In the Windows Local Security Policy, ensure that this user’s role has Log on as a batch job properties.LogOnAsABatch.jpg

    The credential tasks are set to run powershell.exe with these command lines for the create and delete tasks respectively:

    -ExecutionPolicy RemoteSigned -NoLogo -File "C:\CU Environment Sync Scripts\Horizon_Azure_Sync.ps1"  -folderPath "\Datacenter\Virtual Desktops\Horizon Cloud"  -logfile "C:\CU Environment Sync Scripts\HZ Azure Sync.log" -base "cloud-us-2"
     
    -ExecutionPolicy RemoteSigned -NoLogo -File "C:\CU Environment Sync Scripts\Horizon_Azure_Sync.ps1"  -folderPath "\Datacenter\Virtual Desktops\Horizon Cloud"  -logfile "C:\CU Environment Sync Scripts\HZ Azure Sync Deletes.log" -base "cloud-us-2" -Delete
     
  • Citrix Virtual Apps and Desktops Sync Script

    Using our synchronization script, you can automatically populate the ControlUp organizational tree with your Citrix Virtual Apps and Desktops. Our sync script is run as a Windows scheduled task so that when you add or remove machines, those changes are automatically reflected in the organizational tree in ControlUp. You don't have to make any of those changes manually. When the script is run, your ControlUp organization reflects your current Citrix VDI for monitoring and remediation.

    • The sync script is written in PowerShell and stored in our GitHub repository.
    • You set the Windows scheduled task to run the sync script on the ControlUp monitor machine. 

    Prerequisites

    • The sync has to be performed on a machine which has the ControlUp monitor component installed. You can read about Adding a ControlUp Monitor.
    • The ControlUp monitor must be version 8.1.5.600 or higher.
    • The user running the scripts must have a local profile on the ControlUp monitor machine. Ensure that the same user logs onto the machine at some point before running the scripts.
    • The user running the script must be an Active Directory service account that has at least read permission access to the Citrix studio.

    1. Access the scripts from our GitHub repository 

    You download the sync scripts from our GitHub repository of environment scripts which also includes synchronization scripts for other environments.

    1. Download the following scripts:
      CTX_Sync.ps1
      Build-CUTree.ps1 
    2. Copy these scripts to the machine running the ControlUp monitor. These scrips must reside in the same folder on the monitor machine.
    3. Optionally, in a PowerShell window, run this command to see the script's parameters, their descriptions, and default values:
        get-help \<path to the file>\CTX_Sync.ps1

     

    Here are the parameters in the sync script CTX_Sync.ps1. These are the parameters to assign when adding the argument in step 2. Set up a Windows Scheduled Task.
    Name Description
    FolderPath *Mandatory. The target folder in the ControlUp organizational tree to save these objects.
    Preview
    Displays the expected results without committing any changes to the ControlUp environment.
    Delete
    Enables the script to execute removing objects from the ControlUp organizational tree. Use with the preview parameter to see the proposed changes before making them.
    LogFile
    Specify a text file to log the output. Can be used for debugging and with the preview parameter to see the proposed changes. Log data is appended to this file with each run of the script.
    Site
    Specify a ControlUp Monitor site to assign the objects. Default value: default
    Brokers A list of Brokers to contact for Delivery Groups and Computers to sync. Specify multiple brokers in a comma-separated list.
    These Brokers act as
    delivery controllers and know what resources are available for which users. 

    If you have multiple different Citrix environments, for example, you may have multiple Brokers for testing and production environments, we recommend listing the multiple Brokers and using the addBrokersToControlUp parameter.

    includeDeliveryGroup

    Include only these specific Delivery Groups to be added to the ControlUp tree. Specify multiple Delivery Groups in a comma-separated list.
    - If you do not enter a value here, all detected Delivery Groups are captured and updated in the ControlUp tree.

    - Wild cards values are supported. For example: specify "Epic*" to include both "Epic North" and "Epic South".

    - If you enter values for excludeDeliveryGroup parameter, the 'exclude' supersedes any values entered here and will not 'include' them.

    excludeDeliveryGroup

    Exclude specific delivery groups from being added to the ControlUp tree. Specify multiple Delivery Groups to exclude in a comma-separated list.

    - Wild cards values are supported. For example: specify "*CGY" to exclude both "Epic CGY" and "Cerner CGY".

    - If you enter values for includeDeliveryGroup, this 'exclude' supersedes any values entered there and will not 'include' them.

    addBrokersToControlUp Add brokers to the ControlUp Tree. This optional parameter can be specified if you prefer this script to add broker machines as they are detected. If this parameter is omitted, then Broker machines will not be moved or added to your ControlUp tree.
    enabledOnly Include only Delivery Groups that are enabled.
    MatchEUCEnvTree Configures the script to match the same structure used by ControlUp for the EUC Environment Tree. If this parameter is omitted, the Delivery Group is added to the FolderPath. See below for details on how the structure is added to ControlUp if this parameter is enabled.
    maxRecordCount
    Maximum number of items to request from a broker
    batchCreateFolders
    Create folders in batches rather than individually
    force
    Force folder creation if the number exceeds the safe limit
    SmtpServer
    Smtp server to send alert emails from
    emailFrom
    Email address to send alert email from
    emailTo
    Email addresses to send an alert email to
    emailUseSSL
    Use SSL to send an email alert

    MatchEUCEnvTree Parameter

    If you enable this parameter in the Windows Scheduled Task argument running this sync script, any Delivery Group and Broker that is detected as added to your VDI is added to ControlUp as follows:

    $SiteName - |    
      |- Delivery Groups - |  
      | |- DG1 - |
      |   |- Machine001
      |- Brokers - |  
        |- Broker001  

    Meaning that each Delivery Group is added as a separate line under a folder for Delivery Groups with each machine listed separately. And each Broker is added as a separate line under a folder for Brokers.

    This is how this structure would look in your ControlUp organizational tree. TreeBrokersDGs.png

    2. Set up a Windows Scheduled Task

    Follow the steps in this article to create the Windows Scheduled Task but be sure to also follow these instructions for this specific sync script.
    In the Windows Local Security Policy, ensure that this user’s role has Log on as a batch job properties.

    LogOnAsABatch.jpg

    Run the Script as an Active Directory Account

    You must run the script as an Active Directory account that has at least read-only permission within the Citrix studio. We recommend creating a service account in your AD to run this sync script, and that AD account has to be accessible from the monitor machine. 

    When scheduling to run the task, be sure to select:

    • Run whether user is logged on or not
    • Run with highest privileges

    In this example below, the user account is CONTROLUP\svc_sync_citrix created for running this script in these tasks. You can see where to select the above options. ADServiceAccount.png

    Create the Add Task

    Create a task for adding entities to the ControlUp organizational tree. Here's an example of the argument to use based on the parameters described above.

    -ExecutionPolicy RemoteSigned -NoLogo -File "C:\CU Environment Sync Scripts\CTX_Sync.ps1" -folderPath "controlup demo\Virtual Desktops\XenDesktop 7.11" -logFile "C:\CU Environment Sync Scripts\CTX Sync.log" -Brokers cuxenddc01 -addBrokersToControlUp

    In this example of the argument, you can see the following parameters:

    • -folderPath - controlup demo\Virtual Desktops\XenDesktop 7.11
    • -logFile - C:\CU Environment Sync Scripts\CTX Sync.log
    • -Brokers - cuxenddc01 (only one listed)
    • -addBrokersToControlUp - included as an optional parameter

    Create the Delete Task

    Create another task for deleting from the ControlUp organizational tree any entities that have been deleted from your environment. Here's an example of the argument to use based on the parameters described above.

    -ExecutionPolicy RemoteSigned -NoLogo -File "C:\CU Environment Sync Scripts\CTX_Sync.ps1" -folderPath "controlup demo\IL Datacenter\Virtual Desktops\XenDesktop 7.11" -logfile "C:\CU Environment Sync Scripts\CTX Sync Deletes.log" -Brokers cuxenddc01 -Delete -addBrokersToControlUp

     

  • Windows Virtual Desktop Script Integration

    Windows Virtual Desktop (WVD) is a desktop and app virtualization service that runs in the cloud. It’s a service from Microsoft Azure that brokers users to desktops or applications from anywhere in the world. With these scripts, you don't have to switch between consoles to manage your WVD configuration.

    ControlUp has developed a series of scripts that natively integrate into the ControlUp console, allowing you to manage your WVD session hosts and host pools, and all from a single pane of glass.

    You don't have to log onto the Azure portal and can manage these resources directly from the ControlUp console. Using ControlUp, you can perform actions like setting a maximum session limit on the host pool, getting Azure image information, or sending a message to a user through the WVD service.

    To run the ControlUp Script Actions for WVD, you must prepare both Azure and your ControlUp environment. Perform these procedures as described in this article:

    1. Configure Azure App Registration and Service Principal Object for ControlUp Script Actions. Create an Azure user with the necessary role and permissions to enable the integration.
    2. Synchronize Your ControlUp Organization Tree with Your WVD Directory. (Optional) Sets up synchronization so that your ControlUp organization tree reflects your WVD directory. This is an optional advanced step that should be done before the next step but is not mandatory for the integration to work. 
    3. Configure Your ControlUp Console to Monitor and Manage Your WVD Environment

    Once the integration is complete, you’ll be able to:

    • Run the script actions against your WVD environment from your ControlUp console.
    • Configure the load balancing algorithm in real-time.
    • Create triggers for automation to change in response to metrics such as the number of users, CPU load, or nearly anything else.

    Part I - Configure Azure App Registration and Service Principal Object for ControlUp Script Actions

    To use the script actions, a Service Principal account must be created and configured in Azure. This enables running PowerShell scripts against WVD in Azure. The WVD Script Actions use an Azure Service Principal to connect to Azure and run the script. This way, the script actions do not have to start with a popup window that asks for your Azure Credentials.

    Note: The steps here are based on the latest Azure implementation dated 22 July 2020. As this is third-party software, we cannot guarantee the specific field names and steps but are giving you the most updated information as of the date we are publishing this article.

    Create a Service Principal Account in Azure Active Directory

    To create a Service Principal account in Azure Active Directory, you have to create a new registration and secret:

    1. Log onto the Azure portal and use the hamburger menu to navigate to Azure Active Directory > App Registrations. Click New Registration.
    2. Give your account a meaningful name.
    3. Select Accounts in this organization's directory only. Click Register.
    4. Take note of the Application (client) ID and the Directory (tenant) ID information as they are needed in the next procedure for configuring ControlUp.
    5. Click Certificate & secrets to create a secret and click New client secret.
    6. In the Description field, give a meaningful description (i.e. ControlUp secret), select from the Expires options, and click Add.
    7. Copy the secret value to a password manager or temporary file. This is the only time it is displayed and can be copied from the Azure portal. If you don't copy this secret value, you will have to delete this secret and create a new one to ensure you have a valid secret for authentication.

    Assign the Service Principal the required permissions in the Azure AD and for your Azure Subscription

    To ensure the Script Actions can retrieve the assigned WVD resources for a user, the Service Principal account must be assigned a specific role in the Azure Active Directory.

    1. Log onto the Azure portal and use the hamburger menu to navigate to Azure Active Directory > Roles and administrators.
    2. Use the filter to find the Privileged role administrator.
    3. Click Add assignments.
    4. Use the Search filter to search for the ControlUp Service Principal account you just created. Select it and click Add to assign the role to this account.

    In addition to the Azure Active Directory, the Service Principal account must also be assigned a specific role for your Azure Subscription.

    1. Log onto the Azure portal and use the hamburger menu to navigate to Subscriptions > <your subscription name> > Access Control (IAM).
    2. Click Add and select Add role assignment
    3. Under Role, select Contributor, and under Selected members, select the ControlUp Service Principal you just created. 
    4. Click Save to assign this role.

    Part II - Synchronize your ControlUp organization tree with your WVD directory (optional)

    This process is optional and requires some advanced procedures, along with several synchronization scripts that you download from our GitHub repository. It is performed primarily on the ControlUp monitor server and is not mandatory for the integration to work. If you are currently not yet in production with your WVD environment, you can easily skip this whole step and go here.  

    Prerequisites

    • A ControlUp monitor server
    • The following PowerShell modules installed on the ControlUp monitor server:
      • Az.Accounts - from Microsoft
      • Az.DesktopVirtualization - from Microsoft
      • ControlUp.PowerShell.User - installed when you add a ControlUp monitor
    • An Azure Service Principal with sufficient permissions to manage WVD (AppID, DirID & secret) - created in Part I
    • The following WVD synchronization scripts from our ControlUp GitHub repository in the Environment_Synchronization_Scrips folder.
      • WVD_Sync.ps1
      • WVD_Functions.ps1
      • Build_CUTree.ps1
      • Store-AzPSCredentials.ps1

    Prepare the ControlUp monitor server

    To set up the synchronization, prepare the ControlUp monitor server with the proper PowerShell modules and the WVD synchronization scripts.

    1. To set up the monitor server, log onto the ControlUp monitor server with an account that has Administrator privileges.
    2. Open a PowerShell prompt with elevated privileges.
    3. Run the following commands:
      1. Install-Module Az.Accounts -Scope AllUsers
      2. Install-Module Az.DesktopVirtualization -Scope AllUsers
    4. Confirm you have the latest ControlUp PowerShell modules with Get-CUFolders. For details, see ControlUp Powershell Commands.
    5. Download and extract the Environment_Synchronization_Scripts folder from our GitHub repository onto your ControlUp Monitor server.
    6. To store the Service Principal credentials in an encrypted file, so it can be used by the script actions (or other PowerShell scripts that need a connection to Azure), run this script:
      Store-AzPSCredentials.ps1 
    7. Enter the required information. 
      SVPDetails.png
    8. Start the WVD_Sync.ps1 script with the folder path of the directory you want to sync into ControlUp and with the -Preview parameter to see which commands it outputs.  Ensure the folder path parameter ends with \WVD. For example:
      PS C:\Sync> . .\WVD_Sync.ps1 -folderPath "VDI_and_SBC\WVD" 
      -Delete -LogFile C:\swinst\WVD2020-07-22.log -Preview
    9. Once you are comfortable with the proposed changes in the output, remove the -Preview parameter to commit the changes to the organizational tree in the ControlUp console.

    Optional - Set up a scheduled task to periodically perform the synchronization

    You can configure a Windows task to periodically run these scripts so the organizational tree in your ControlUp console is synchronized with your WVD.

    Note: The steps here were run on a Windows Server 2019 machine running the ControlUp monitor. Keep in mind that the Az.DesktopVirtualization PowerShell module requires PowerShell version 5.1 or up and .NET Framework version 4.7.2 or later. These are the most updated steps for these versions as of the date we are publishing this article.

    1. Open the Windows Task Scheduler on the ControlUp monitor server machine and select Create Task...
    2. In the General tab, give the task a name, such as Synchronize WVD to ControlUp.
    3. Under Security options:
      1. Check that the user account is the same as the one you used to run the Set-AzSPCredentials.ps1 script.
        Or you can rerun the credential script under the account you want to use for this periodic synchronization.
      2. Select the option to Run whether user is logged on or not. 
    4. In the Triggers tab, create a new trigger and set the schedule for running this task.
    5. In the Actions tab, create a new action with the following options and parameters:
      Action Start a program
      Program/script powershell.exe
      Add arguments (optional) -file C:\Sync\WVD_Sync.ps1 -folderPath "VDI_and_SBC\WVD" -Delete -LogFile C:\swinst\WVDSync.log
      Start in (optional) C:\Sync

    6. Run the scheduled task and review the log file to validate the operation.

    Part III - Configure the ControlUp Console to manage Windows Virtual Desktop (WVD) resources

    This section configures the integration between the ControlUp Console and your WVD environment so you can monitor and manage your WVD resources directly from ControlUp.

    Note: If you chose not to perform Part II, you can perform this configuration but you must manually name a folder in your ControlUp organization tree: \WVD.

    Prerequisites

    WVD is a cloud service so there are some prerequisites that must be installed alongside your ControlUp Console to activate these management actions. 

    • The following PowerShell modules installed on the console server and the machine running the script actions (if it's not the console):
      • Az.Account
      • Az.Resources
      • Az.DesktopVirtualization
      • AzureAD
        Note: The modules can be installed from the PowerShell Gallery using the Install-Module cmdlet. Administrator rights are required to install modules. (In Windows 10, you can install the modules in the scope of the current user which works for virtual machines if you don't have local admin permissions.)
    • PowerShell session is set to use at least TLS1.2 for the communication to the PowerShell Gallery when installing the modules.
    • An Azure Service Principal with sufficient permissions to manage WVD with the required Service Principal properties (AppId, DirId, and Secret) - created in Part I
    • .NetFramework 4.7.2 - required for the Az PowerShell Module

    Run the WVD Set Azure Service Principal Credentials script action

    To run the different WVD script actions that are available to ControlUp, you must first run the WVD Store Azure Service Principal Credentials script. This script stores the required Service Principal information in a local encrypted file which is linked to the username and machine running the script.

    For details on using script-based actions in ControlUp, you can read this article.

    In your ControlUp Console in machine view, right-click a machine (recommended under the \WVD folder) and select Script Actions > WVD Store Azure Service Principal Credentials

    ScriptAction.png

    When you run this script action, you are asked for the required Azure Service Principal information in this popup window: 

    ScriptActionDialog.png

    Enter the information that you previously stored for the Service Principal.

    This information is stored (locally) on the machine running the script in an XML file with an encrypted app secret. To validate that the correct secret appears, access the XML and check that the UserName and Value fields are not empty: 

    XMLcheck.jpgThis stored Service Principal information is used by the other WVD Script Actions, such as the WVD Get Hostpool.

    ScriptAction2.png

     

    ActionResults.png