Citrix Application Probe Agent unattended installation

This article shows you how to script the Citrix Application Probe Agent unattended installation and configuration using PowerShell.

Table of Contents

Introduction

The contents of this article applies to:

  • Citrix Application Probe Agent version 1.0.0.0 (released with XenDesktop 7.18 in Q2 2018)
  • Microsoft Windows 10 1709 and higher

As per Citrix: "Application probing automates the process of checking the health of XenApp and XenDesktop applications that are published in a Site. The results of application probing are available in Director."

I strongly urge you to read the following articles if you are new to application probing:

An overview of the Citrix Application Probe Agent

Before going into the details of the actual installation and configuration, let us first take a closer look at some of the characteristics of the Citrix Application Probe Agent:

  • Target device:
    Install this component on the local client. This software is NOT intended for virtual servers and desktops with the Citrix VDA installed.
  • Installation file name:
    CitrixAppProbeAgent.msi
  • Version:
    1.0.0.0
  • Installation parameters:
    Standard MSI parameters only (e.g. /qn for silent installations or /l*v C.\logfile.log to generate a log file).
  • Uninstallation parameters:
    The software can be uninstalled using the normal MSI uninstall parameters: MsiExec.exe /X{86CFA6FB-AE23-44EB-BA85-BFF09A72F1B6}.
  • Default installation directory:
    C:\Program Files (x86)\Citrix\Citrix Probe Agent
  • Shortcuts:
    Yes, the shortcut Citrix Probe Agent is created on the public desktop.
  • Log file:
    Default MSI log file, if specified on the command line (/l*v %LogFile%). The installation does not create a log file by default.
  • Installation dependencies:
    Citrix Receiver (minimum version 4.8).
  • Other dependencies:
    No
  • Reboot required:
    No
  • Service:
    Citrix Probe Agent Service (the service name is: ProbeAgent).
  • ADMX files:
    No
  • Ports and firewall:
    No (communication takes place within the HDX protocol).
  • Download location:
    The Citrix Application Probe Agent can be downloaded as a stand-alone component on the Citrix download page.
  • Documentation:

Prerequisites

Citrix application probing has the following prerequisites:

  • Delivery Controller version 7.18 or later.
  • Citrix Receiver version 4.8 or later. In case Citrix Receiver is not installed before attempting to install the Citrix Application Probe Agent, the installation will end in an error (error 1603 to be precise).Citrix Application Probe Agent unattended installation - Warning install Citrix Receiver firstIn the event log you see the following error event:

    Citrix Application Probe Agent unattended installation - Installation error 1603 in Event Log Citrix Receiver not installedTo automate the installation and configuration of Citrix Receiver see the article Citrix Receiver unattended installation with PowerShell on this website.

  • HTTP Basic authentication has to be enabled on the StoreFront store:Citrix Application Probe Agent unattended installation - StoreFront Authentication Methods add HTTP BasicTo automate the configuration of the store authentication methods with PowerShell, see the section Manage Authentication Methods in the article Translating the Citrix StoreFront console to PowerShell on this website.

Citrix Director supports the default form based authentication. Therefore no additional configuration in Director is required.

Installing the Citrix Application Probe Agent with PowerShell

The installation of the Citrix Application Probe Agent is pretty straightforward: it is only a simple MSI installation without any custom parameters. The following command line installs the probe agent silently including logging:

msiexec /i CitrixAppProbeAgent.msi /qn /l*v C:\Logs\CitrixAppProbeAgent.log

I recommend using my PowerShell Function Library together with the scripting template found on this website. This is what I use in the complete installation script below. The function DS_InstallOrUninstallSoftware takes care of the installation.

Citrix Application Probe Agent unattended installation - Screenshot PowerShell script probe agent installation

Configuring the Citrix Application Probe Agent with PowerShell

The manual configuration of the Citrix Application Probe Agent can be started by executing the file ProbeEndpointUI.exe in the installation directory C:\Program Files (x86)\Citrix\Citrix Probe Agent. You can also start the wizard by double clicking the
shortcut Citrix Probe Agent on the desktop:

C:\Users\Public\Desktop\Citrix Probe Agent.lnk

This shortcut is created on the public desktop during installation.

Note: the complete installation script in the section below deletes the public shortcut Citrix Probe Agent.

This ProbeEndpointUI.exe starts the Citrix Application Probe Agent wizard.

Citrix Application Probe Agent unattended installation - Screenshot Probe Agent wizard

The wizard requires the following parameters:

  • StoreFront:
    • StoreFront URL (make sure to use the web store!)
    • StoreFront user name (has to be in the format domain\user or user@domain.com)
    • Password
  • Director:
    • Director URL
    • Director user name (can be in the format domain/user or user. If the domain is not specified, the domain has to be specified in the Domain field)
    • Domain (this value is only required if the domain is not specified in the user name)
    • Password
    • Site (farm) name

After configuring the StoreFront and Director settings, all settings are stored in the registry, here to be precise:

  • StoreFront configuration
    • Registry key: HKLM\SOFTWARE\WOW6432Node\Citrix\ProbeAgent\SF
    • Registry values:
      • param1 -> contains the StoreFront URL
      • param2 -> contains the name of the StoreFront user account (the format must be domain\user).
      • param3 -> contains the password for the StoreFront user account (the password is not stored in a readable format)
  • Director configuration
    • Registry key: HKLM\SOFTWARE\WOW6432Node\Citrix\ProbeAgent\DIR
    • Registry values:
      • param1 -> contains the Director URL
      • param2 -> contains the name of the Director user account including the domain name (domain\user) or without the domain name (user). In case the domain name is not added, the domain has to be specified (param4)
      • param3 -> contains the password for the Director user account (the password is not stored in a readable format)
      • param4 -> contains the domain name (this value is empty if the user name already includes the domain name (domain\user)
      • param5 -> contains the site (farm) name
      • param6 -> contains the (IIS) site ID (the default is 1)

There are two ways how to configure the probe agent silently:

Configuring the Probe Agent through a named inter-process communication pipe

In the complete installation script below, the probe agent is configured using a named pipe. A named pipe is a stream-based mechanism for inter-process communication (IPC). The function WriteToPipe is at the heart of this.

Citrix Application Probe Agent unattended installation - Screenshot PowerShell script WriteToPipe function

I have to be clear on one thing though: this very cool and relatively complex piece of automation was not written by me. This code was created by Sharath Babuthe Citrix developer of the Application Probe Agent (many thanks Sharath!). And I also extend a big thank you to fellow CTA and Citrite Martin Zugec for his continuous help and support!

Note: when configuring the probe agent in production, I strongly recommend to use the complete installation script using a 256-bit AES encrypted password!

Configuring the Probe Agent by exporting and importing the registry

The second method how to automate the configuration of the probe agent is not as "sexy" as the previous one, but it works. After configuring the probe agent manually, the registry values in the aforementioned registry keys can be exported and saved as a *.REG file. This registry file can than be imported when installing and configuring the probe agent.

In case you use my PowerShell Function Library, you can use the function DS_ImportRegistryFile to import the registry file.

As said, this method works, but the obvious disadvantage is that you first have to manually configure the probe settings to be able to export the *.REG file. Since the probe agent should use different StoreFront credentials for each worker, you will have to repeat this process multiple times.

Complete installation script

The scripts below include both the installation and configuration of the Citrix Application Probe Agent, including detailed logging and error handling. One script uses a plain-text password (good for testing) and the other one a secure 256-bit AES key (for production). Besides the security level of the password, the scripts are the same:

Note: when configuring the probe agent in production, I strongly recommend to use the Complete installation script using a 256-bit AES encrypted password!

The scripts are based on my installation template. Also, the functions used in the scripts require my PowerShell Functions Library to be present on the local system. This means that before you can use the script, you need to copy the PowerShell module file DS_PowerShell_Function_Library.psm1 to the local system first.

In order to use the scripts, please follow these steps:

The complete installation scripts write a detailed log file. By default you can find the log file here: C:\Logs\Citrix Application Probe Agent.log. The directory and log file name may be different in case you changed the variables $BaseLogDir and $PackageName.

Complete installation script using an unsecure plain-text password

Complete installation script using a 256-bit AES encrypted password

Use this script for your production. The only difference compared to the complete installation script using an unsecure plain-text password is that a 256-bit AES key file and accompanying password file are used to securely parse the password.

Please see the section Using a 256-bit AES key file and a password file in the article Encrypting passwords in a PowerShell script to learn how to create these two files. It is quite simple, I promise.

Just make sure to copy the key file and password file to a directory on the local machine or on a file share and that lines 84 and 85 in the script point to the correct directory.

One more thing. Please note that the inter-process communication pipe requires that the password is parsed as a standard string (the PSCredential object cannot be used in this case). The Marshal class handles the decrypting of the secure password.

Citrix Application Probe Agent unattended installation - Screenshot PowerShell script decrypt secure string

You can check if the script did its job by running the configuration wizard once again. Since the script deleted the desktop shortcut you can either run the wizard from the start menu (Citrix \ Citrix Probe Agent) or execute it directly ("C:\Program Files (x86)\Citrix\Citrix Probe Agent\ProbeEndpointUI.exe"). Click the top right Edit button and go through each step of the wizard without changing anything until you reach the last page. If you reach the end without any (authentication) errors your automation routine worked.

Citrix Application Probe Agent unattended installation - Probe Agent wizard

I hope this article was of some help to you. As always, happy scripting!

Share this post:
Dennis Span on EmailDennis Span on LinkedinDennis Span on Twitter
Dennis Span
Dennis Span
Dennis Span works as a Senior Citrix Architect for a large insurance company in Vienna, Austria. He holds multiple certifications such as CCE-V, CCIA and CCEA. In 2017, Dennis became a Citrix Technology Advocate (CTA). Besides his interest in virtualization technologies and blogging, he loves spending time with his family as well as snowboarding, playing basketball and rowing. He is fluent in Dutch, English, German and Slovak and speaks some Spanish.

3 thoughts on “Citrix Application Probe Agent unattended installation

  1. Pingback: Director 7.18 – Carl Stalhood

  2. Pingback: Detailed Change Log – Carl Stalhood

  3. Pingback: Director 1808 – Carl Stalhood

Leave a Reply

Your email address will not be published.

*

This site uses Akismet to reduce spam. Learn how your comment data is processed.