# Citrix Virtual Apps and Desktops connector {% hint style="warning" %} This documentation references external sources. Nexthink does not have control over the accuracy of third-party documentation, nor any external updates or changes that might create inconsistencies with the information presented on this page. Please report any errors or inconsistencies to [Nexthink Support](https://support.nexthink.com/). {% endhint %} Nexthink Connector for Citrix Virtual Apps and Desktops (CVAD) retrieves important information about your Citrix environments, most notably the name of the Desktop Delivery Group to which the virtual machines belong. The connector ships with an accompanying live dashboard that you can download in a form of a library pack. Refer to the [Desktop Virtualization Optimization](https://edocs.nexthink.com/nexthink-infinity/infinity-specifications/desktop-virtualization-classic/desktop-virtualization-optimization-classic) extended documentation for more details. This installation guide aims to help you install the connector for CVAD securely. Your security team should review the installation steps described in this document and adjust them to meet your organization’s security policy. {% hint style="info" %} Nexthink Connector for CVAD and Nexthink Collector work together to provide additional information about CVAD environments. This means that in addition to installing the Nexthink Connector for CVAD, you must also install Nexthink Collector on all virtual devices in your Citrix environment. {% endhint %} ## Device fields The connector for Citrix Virtual Apps and Desktops (CVAD) imports the following device virtualization fields. | **Nexthink Field** | **Description** | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Virtualization desktop pool name | The hardware characteristics of the associated VMs. | | Virtualization desktop pool type |

The type of the desktop pool. Possible values are:

shared
personal
pooled

| | Virtualization hostname | The physical device hosting the VM. It may be empty for those machines hosted in a cloud vendor, such as Azure. | | Virtualization hypervisor name | The hardware virtualization system which is being used. | | Environment name | The name of the connector instance which enriches the virtual device. | | Desktop broker | The name of the desktop virtualization product used. In this case, `citrix_cvad`. | | Disk image | The name of the disk image used to deploy the VM. | ## Nexthink connector server To limit the risk of disrupting the Citrix Desktop Delivery Controller (DDC), Nexthink recommends installing the Nexthink Connector for CVAD on a separate server. However, the expected impact to the DDC is minimal, therefore for proof-of-value installations this can be done directly on the Citrix server. ### Prerequisites * Installed Windows PowerShell 5.1. * Execution policy set to **bypass**. * The following PowerShell modules: * [Logging 4.8.5](https://www.powershellgallery.com/packages/Logging/4.8.5) * [CredentialManager 2.0](https://www.powershellgallery.com/packages/CredentialManager/2.0) * Installed Citrix Powershell SDK 2203 LTSR or newer. Refer to the [SDKs and APIs for Citrix Virtual Apps and Desktops 7 2203 LTSR](https://docs.citrix.com/en-us/citrix-virtual-apps-desktops/2203-ltsr/sdk-api.html) documentation for the installation procedure using Citrix Studio. * Joined domain. * [Downloaded Nexthink Connector for CVAD](https://download.nexthink.com/integrations/Citrix+OnPrem+Connector/1.7.12/CitrixConnector-1.7.12.zip). * The following accounts: * Citrix Read Only Account * Domain Account * Local user account on the machine #### **URLs to allow through firewall/proxy for powershell `Install-Module`**

Purpose	URL
PowerShell Gallery	`https://www.powershellgallery.com`
NuGet provider	`https://www.nuget.org`
NuGet API	`https://api.nuget.org`
CDN for packages	`https://www.powershellgallery.com/api/v2/`
Alternate NuGet V2 API	`https://www.nuget.org/api/v2/`
Certificate revocation	`http://crl.microsoft.com` (normally optional; sometimes necessary)

#### Additional Considerations * In the ICA policy settings, ensure the **Virtual channel allow list** is set to **Disabled**. For more information, see the [Citrix documentation](https://docs.citrix.com/en-us/citrix-virtual-apps-desktops/policies/reference/ica-policy-settings/virtual-channel-allow-list-policy-settings). * If SSL inspection is enabled on your proxy, ensure it doesn't break the TLS handshake. * If you're behind a **proxy**, make sure `PowerShell` is configured to use it by running the following command: {% code overflow="wrap" %} ```powershell [System.Net.WebRequest]::DefaultWebProxy.Credentials = [System.Net.CredentialCache]::DefaultNetworkCredentials ``` {% endcode %} #### **Test connectivity** You can test access using a PowerShell terminal by running the following command: ```powershell Invoke-WebRequest https://www.powershellgallery.com ``` ### Networking The Nexthink Connector for CVAD needs to connect to a Citrix Desktop Delivery controller, Citrix Director and the Nexthink API. * The Nexthink connector communicates with the Nexthink cloud over TCP port 443. * Communication between the Nexthink connector server and the Citrix Director uses TCP port 443. * The connection to the Citrix DDC depends on the Citrix PowerShell SDK and follows your PowerShell configuration. By default, PowerShell communicates over TCP ports 5985 and 5986. The following figure shows a simplified architecture with a connection between the connector and a delivery controller:

### Service account for scheduled tasks The Nexthink Connector for CVAD will run as a scheduled task, one per CVAD environment, and needs to be able to access the Citrix APIs. To limit security concerns, Nexthink recommends using a local user account on the Nexthink connector server or a regular domain user account without any special privileges at the domain level. The following guide uses a local account on the Nexthink connector server. 1. Log on as an administrator to the server that will run the Nexthink Connector for CVAD. 2. Launch the local users and groups console by running the command `lusrmgr.msc` from the start menu.

3. Right-click on the **Users** folder in the **Local Users and Groups (Local)** directory and select **New user…** 4. Create a user account according to your organization's naming conventions. Make a note of the **User name** and **Password** as you will need these later when creating a scheduled task. To safeguard the functionality of the connector, select the following options: 1. **User cannot change password** 2. **Password never expires**

5. Click **Create**. 6. Next, open the local group policy editor by executing `gpedit` from the start menu. 7. Navigate to the **Computer Configuration > Windows Settings > Security Settings> Local Policies > User Rights Assignment** and look for the policy called **Log on as a batch Job**. 8. Open the policy and click on **Add User or Group** to add the previously created user to the list.

### Installing the connector 1. [Download the Nexthink Connector for CVAD](#connectorforcitrixvirtualappsanddesktops-prerequisites). 2. Extract the zip file to a folder on your system. Nexthink recommends placing it in the following folder:\ `C:\program files\Nexthink\Connectors\Citrix` 3. Apply **Modify** permissions for the **Logs** folder for the user account you created earlier.

### Nexthink Enrichment API credentials The connector for CVAD needs appropriate credentials to connect to the Nexthink Enrichment API. Nexthink stores the credentials safely in the credential store of the local user account you created earlier. 1. Refer to the [API credentials](https://developer.nexthink.com/docs/api/api-credentials) documentation for step-by-step guidance. When you save the API credentials, a new window containing the Client ID and the Secret key appears. Make a note of the information as it will not be accessible once you close the window. {% hint style="warning" %} When creating the credentials, ensure that in **Permissions** you have **Enrichment API** selected. {% endhint %}

2. On the server that will be running the Nexthink Connector for CVAD, open PowerShell under the credentials of the local user you created earlier using the `runas` command in the command line: ```powershell runas /user:nxt-ctx-connector powershell.exe ```

3. In the newly opened PowerShell window, add the API credentials you just created in the Nexthink web interface by running the following command: {% code overflow="wrap" %} ```powershell New-StoredCredential -Target "nxt-ctx-connector" -UserName -Password -Persist LocalMachine ``` {% endcode %} Replace the `` and `` with the values you noted down when creating the API credentials. Make a note of the `TargetName` you used with `-Target` as you will need this value for the configuration file.

{% hint style="info" %} In the `config.json` [configuration file](#connectorforcitrixvirtualappsanddesktops-updatingtheconfigurationfile), these credentials are stored in `"NexthinkAPI"`. The `TargetName` used with `-Target` is stored in `"WindowsCredentialEntry"`. {% endhint %} ### Updating the configuration file For the configuration file update, you need the URL of your Nexthink Cloud API instance. The URL pattern looks like this: `instance.api.region.nexthink.cloud`. See the steps listed below for more details. {% hint style="info" %} If you do not know your region, reach out to your Nexthink representative to obtain this information. {% endhint %} 1. Locate the folder where you unzipped the connector for CVAD. 2. Navigate to the **Config** folder and open the `config.json` file using a text editor. 3. Scroll to the `"NexthinkAPI"` section.

{
    "_Info": "This is the JSON based configuration for Citrix Virtual Apps and Desktops connector",
    "Info": {
        "Project": "copla-citrix-onprem-connector",
        "ConfigVersion": "1.1.0"
    },
    "Logging": {
        "LogRetentionDays": 7,
        "LogLevel": "INFO"
    },
    "CitrixEnvironments": [
        {
            "Name": "<citrix-environment-name>",
            "CitrixControllerFQDN": "<citrix_controller_host>",
            "CitrixDirectorFQDN": "<citrix_director_host>",
            "WindowsCredentialEntry": "<citrix-user-credentials>"
        },
        {
            "Name": "<citrix-environment-name2>",
            "CitrixControllerFQDN": "<citrix_controller_host2>",
            "CitrixDirectorFQDN": "<citrix_director_host2>",
            "WindowsCredentialEntry": "<citrix-user-credentials2>"
        }
    ],
    "NexthinkAPI": {
        "HostFQDN": "<nexthink_api_host>",
        "WindowsCredentialEntry": "nxt-ctx-connector",
        "RequestBatchSize": "1000"
    }
}

4. Change the following values under the `"NexthinkAPI"` section: * Replace the `"HostFQDN"` value with the URL of your Nexthink cloud API instance using the format `instance.api.region.nexthink.cloud` where `instance` and `region` are placeholders. * Replace `instance` with the name of the instance * Replace `region` with the name of one of the following regions: * `us` for the United States * `eu` for the European Union * `pac` for Asia-Pacific * `meta` for the Middle East, Turkey and Africa * If needed, you can refer to this URL example: `gwy-eu-west-3-fuji-rest.api.eu.nexthink.cloud` * Replace the `“WindowsCredentialEntry"` with the `TargetName` of the credentials you noted down from the PowerShell window earlier, for example:\ `"WindowsCredentialEntry": "nxt-ctx-connector",` {% hint style="warning" %} To replace the `"CitrixEnvironments"` values in the configuration file and set up a connection to the CVAD farm, refer to [#connectorforcitrixvirtualappsanddesktops-updatingtheconfigurationfile.1](#connectorforcitrixvirtualappsanddesktops-updatingtheconfigurationfile.1 "mention"). {% endhint %} ## Setting up a connection to the CVAD farm The previous section described the basic configuration of the Nexthink Connector for CVAD. This section will help you set up a connection to a CVAD environment. Repeat the procedures in this section for every CVAD environment you need to connect to. ### Citrix DDC Nexthink Connector for CVAD connects to the Citrix Desktop Delivery Controller (DDC) to retrieve data from the Citrix Monitoring API provided by the Citrix Director and the Citrix PowerShell SDK. You need the Citrix DDC name to properly configure the connector. Make sure the Citrix Director is installed on the DDC and make a note of the fully qualified domain name (FQDN) of the Citrix DDC. ### Creating a read-only Citrix administrator The Nexthink Connector for CVAD needs read-only access to the Citrix Director API and the Citrix PowerShell SDK. In order to do this, create a domain user account without any special privileges and make a note of the username and password. 1. Launch the Citrix Studio console and start the administrator creation wizard from **Configuration > Administration.** 2. Right-click on **Administration** and select **Create Administrator.**

3. Click the **Browse…** button and select the service account that you previously created. * Set the scope to **All** and click **Next** to continue

4. Select the **Read Only Administrator** role and click **Next** to continue.

5. Select **Enable administrator** and click **Finish**.

### Setting up stored credentials 1. On the server that will be running the Nexthink Connector for CVAD, open PowerShell under the credentials of the local user you created earlier using the `runas` command on the command line: ```powershell runas /user:nxt-ctx-connector powershell.exe ```

2. In the newly opened PowerShell window, add the API credentials you just created in the Nexthink web interface by running the following command: {% code overflow="wrap" %} ```powershell New-StoredCredential -Target "nxt-ctx-prod" -UserName -Password -Persist LocalMachine ``` {% endcode %} Replace the `` and `` with the values you noted down when creating a domain user account with a read-only Citrix administrator.\ \ Make a note of the `TargetName` you used as you will need this value for the configuration file.

{% hint style="info" %} In the `config.json` [configuration file](#connectorforcitrixvirtualappsanddesktops-updatingtheconfigurationfile.1), these credentials are stored in `"CitrixEnvironments"`. The `TargetName` used with `-Target` is stored in `"WindowsCredentialEntry"`. {% endhint %} ### Updating the configuration file Each CVAD environment has its own section in the configuration file. The configuration file that comes with the connector contains an example of how to configure multiple environments. If needed, create a copy of the original `config.json` file for future reference. 1. Locate the folder where you unzipped the connector for CVAD. 2. Navigate to the **Config** folder and open the `config.json` file using a text editor. 3. Scroll to the `"CitrixEnvironments"` section and remove the second item on the list starting with `{ "Name"...` and ending with `"`nxt-ctx-prod`"}`. The code should look similar to the following:

{
    "_Info": "This is the JSON based configuration for Citrix Virtual Apps and Desktops connector",
    "Info": {
        "Project": "copla-citrix-onprem-connector",
        "ConfigVersion": "1.1.0"
    },
    "Logging": {
        "LogRetentionDays": 7,
        "LogLevel": "INFO"
    },
    "CitrixEnvironments": [
        {
            "Name": "<citrix-environment-name>",
            "CitrixControllerFQDN": "<citrix_controller_host>",
            "CitrixDirectorFQDN": "<citrix_director_host>",
            "WindowsCredentialEntry": "nxt-ctx-prod"
        }
    ],
    "NexthinkAPI": {
        "HostFQDN": "<nexthink_api_host>",
        "WindowsCredentialEntry": "nxt-ctx-connector",
        "RequestBatchSize": "1000"
    }
}

Change the following values in the `"CitrixEnvironments"` section: * Replace `` with the name of your environment. * Replace `` with the name of the Citrix DDC. * Replace `` with the name of the Citrix Director. * Replace `"nxt-ctx-prod"` with the `TargetName` of the stored credentials you created earlier in PowerShell. * Make a note of the identifier as you will need it later. ### Testing the connector 1. On the server that will be running the Nexthink Connector for CVAD, open PowerShell under the credentials of the local user you created earlier using the `runas` command on the command line: ```powershell runas /user:nxt-ctx-connector powershell.exe ``` 2. Change to the directory where you installed the connector, for example:\ `cd 'C:\Program Files\Nexthink\Connectors\Citrix\'` 3. Run the `Citrix-Connector-Auto-Updater.ps1` script with the following command: ```powershell .\Citrix-Connector-Auto-Updater.ps1 ``` 4. Run the `Citrix-Connector-Runner.ps1` script with the following command: ```powershell .\Citrix-Connector-Runner.ps1 -CitrixEnvironment ``` Replace `` with the name you chose for the environment. The expected output for both scripts is `0`, similar to the following figure:

Correct execution should provide a log such as the following:

After executing the command, the PowerShell window closes and a folder with the name you chose for the connection should appear. In the folder, you will find a log file with the result of the test. ### Setting up a scheduled task 1. Open the task scheduler and select **Create task…**

2. Name the task and change the user to the service account that you previously created in the **General** tab. Select **Run whether user is logged on or not**. Click **OK**.

3. Switch to the **Triggers** tab. 4. Under **Advanced settings > Repeat tasks every**, select an adequate frequency. Click **OK**. {% hint style="info" %} Nexthink recommends setting the frequency to a low value, such as 1 minute, to enable a fine granularity for data collection. However, if this value is too low for your infrastructure, you can go up to even a 1-hour granularity. {% endhint %}

5. Switch to the **Actions** tab and create a new action. 6. Paste the full path of the `Citrix-Connector-Auto-Updater.ps1` script into the **Add arguments (optional)** field, including the environment name, for example `-ExecutionPolicy Bypass -File "C:\Program Files\Nexthink\Connectors\Citrix\Citrix-Connector-Auto-Updater.ps1"`.\ Start in the folder containing the script, for example `C:\Program Files\Nexthink\Connectors\Citrix` Click **OK**.

7. A window will prompt you to enter the password of the service account. Click **OK**.

8. Schedule another one for `Citrix-Connector-Runner.ps1` script into the **Add arguments (optional)** field, including the environment name, for example `-ExecutionPolicy Bypass -File "C:\Program Files\Nexthink\Connectors\Citrix\Citrix-Connector-Runner.ps1" -CitrixEnvironment "Citrix PROD"`. Start in the folder containing the script, for example `C:\Program Files\Nexthink\Connectors\Citrix` .Click **OK**. *** RELATED TOPIC * [API Credentials](https://developer.nexthink.com/docs/api/api-credentials) [^1]: This value must match the parameter for `New-StoredCredential -Target`.