Citrix App Layering Agent unattended installation

This article shows you how to script the Citrix App Layering Agent unattended installation and registration using PowerShell.

Change Log
26.09.2017: updated to Citrix App Layering Agent version 4.5. This article was originally written for version 4.4 to which it still applies. I did not test the installation routine with versions older than 4.4, but it may work.
06.12.2017: updated to Citrix App Layering Agent version 4.6.
15.01.2018: updated to Citrix App Layering Agent version 4.8.
Table of Contents

Introduction

The contents of this article applies to:

  • Citrix App Layering Agent version 4.4 to 4.8 (may also work for older versions)
  • Citrix Provisioning Server 7.15 to 7.16 (should work from Provisioning Server version 7.7 and higher though)
  • Microsoft Windows Server 2016 Build 1607

As per Citrix: "The App Layering Agent enables the App Layering appliance (Enterprise Layer Manager) or the App Layering packaging machine virtual machine to run PowerShell commands locally. [...] The App Layering Agent is required for Provisioning Services and connector scripts".

Note: the Citrix App Layering management server is called the Enterprise Layer Manager, or ELM in short. I use the abbreviation ELM throughout the rest of this article.

If you want the ELM to automatically publish a consolidated VHDX file to your Provisioning Servers you need to install the App Layering Agent on at least one Provisioning Server.

For a complete overview of Citrix App Layering, I strongly urge you to read the following articles:

An overview of the Citrix App Layering Agent

Before going into the details of the actual installation itself, let us first take a closer look at some of the characteristics of the Citrix App Layering Agent:

  • Target device:
    Install this component on any machine on which the ELM is supposed to run PowerShell commands locally, for example on your Provisioning Servers. This software is NOT intended for the local client device nor for virtual servers and desktops with the Citrix Virtual Delivery Agent (VDA) installed!
  • Installation file name:
    • citrix_app_layering_agent_installer.exe
    • Citrix App Layering Agent.msi (extracted)
  • Version:
    4.4 to 4.8
  • Installation parameters:
    The official command for unattended installation is: citrix_app_layering_agent_installer.exe /S /v"/qn", but this does not work without throwing an error. This is explained in the section Scripting the Citrix App Layering Agent.
  • Uninstallation parameters:
    The software can be uninstalled using the normal MSI uninstall parameters: MsiExec.exe /I{886FB0B5-5F09-4FCD-B329-B16AC8BA9E3D}.
  • Log files
    • Default MSI log file (if not changed on the command line): %Temp%\MSIxxxxx.log. The name of the log file is generated at installation time and never the same.
    • Default log file of the executable file citrix_app_layering_agent_installer.exeC:\Program Files (x86)\Citrix\Agent\Logs\applayering.agent.log
  • Installation dependencies:
    • .NET Framework 4.5 or higher
    • PowerShell 3.0 or higher
    • On a Windows 2008 R2 Provisioning Server run the PowerShell command Enable-PSRemoting to enable the remote execution of PowerShell commands.
    • On a Provisioning Server, the PVS console as well as the PowerShell snap-in has to be installed. Please see the article Citrix Provisioning Server unattended installation for detailed information on how to do this.
  • Other dependencies:
    No
  • Reboot required:
    No
  • Service:
    Citrix App Layering Agent (the service name is: Citrix.AppLayering.Agent)
  • ADMX files:
    No
  • Ports and firewall:
    No (outbound communication to port 8016 on the ELM only)
  • Download location:
    The Citrix App Layering Agent can be downloaded as a stand-alone component on the Citrix download page in the section Tools.
  • Reference:

Scripting the Citrix App Layering Agent

Before we start, I need to mention that the installation is not as straightforward as one might expect. I expected the installation to be a simple execution of the citrix_app_layering_agent_installer.exe including some parameters. Unfortunately, the underlying MSI does not work well for unattended installations. I explain all this in the following paragraphs.

Step 1: Installing the Citrix App Layering Agent

By default, the unattended installation should be triggered as follows:

"C:\Temp\citrix_app_layering_agent_installer.exe" /S /v"/qn"

Citrix App Layering Agent unattended installation - Citrix App Layering Agent help

This unfortunately does not work. At the end, the following error is thrown:

Citrix App Layering Agent unattended installation - installation error connecting to ELM

The explanation why this error is thrown takes a bit of time, therefore I describe it in a separate section below.

OK, so how do we install the agent? The correct command is as follows:

"C:\Temp\citrix_app_layering_agent_installer.exe" /S /v"/qn /l*v "C:\Logs\Install_CitrixAppLayeringAgent.log" PORT=8016 SKIP_ELM_REGISTRATION=1 TRANSFORMS="C:\Temp\CitrixAppLayeringAgentSkipELMRegistration.mst""

Note: make sure that the log directory exists before running the unattended installation to prevent errors!

Let's analyze the various parameters. The first two parameters are for the executable file citrix_app_layering_agent_installer.exe:

  • /S - This parameter tells the executable file to install the software silently
  • /v - This parameter initiates the parsing of the MSI parameters
Note: the executable citrix_app_layering_agent_installer.exe is merely a wrapper containing an MSI file.

The parameters which come after /v are the MSI parameters:

  • /qn - This parameter sets the user interface (UI) level; /qn means "no UI".
  • /l*v "C:\Logs\Install_CitrixAppLayeringAgent.log" - This parameter tells the MSI to create a log file (verbose).
  • PORT=8016 - This parameter allows the administrator to set the listening port for the App Layering Agent service. The default port is 8016. After installation, open a command window and use the NetStat command to check if the agent service is actively listening on the configured port: netstat -a.Citrix App Layering Agent unattended installation - netstat listening port 8016
  • SKIP_ELM_REGISTRATION=1 - This parameter determines if the ELM registration is skipped or not (0 = do not skip; 1 = skip). This parameter does not work without the custom transform file (explained below).
  • TRANSFORMS="C:\Temp\CitrixAppLayeringAgentSkipELMRegistration.mst" - This parameters adds a transform file (*.MST) to the MSI file (explained below).
Note: when using the citrix_app_layering_agent_installer.exe, the full path to the transform file is required. If you do not use the full path, the installer tries to locate the transform file in the temporary directory used to extract the MSI file (see below). The installation will fail, since the MST file will not be present in this directory.

In the command line I have added a custom made transform file (*.MST). I had to create this transform file to fix a small error in the original MSI file. Please see the section below for a more detailed explanation on this matter. You can download the MST file here:

Unidesk logo

Download custom MST file for Citrix App Layering Agent 4.4 to 4.8

In the section Complete installation script I prepared a PowerShell script which includes the installation and registration process including detailed logging and error handling. In this script I use the MSI file instead of the executable file citrix_app_layering_agent_installer.exe.

This is how you retrieve the MSI file.

First, extract the MSI file. Start the citrix_app_layering_agent_installer.exe manually and wait until the first window of the MSI setup is shown.

Citrix App Layering Agent unattended installation - installation wizard first window

Do NOT click Next! Instead, open your temp folder (%temp%). The installer will have created two folders and an MSI log file.

Citrix App Layering Agent unattended installation - contents temp folder

In one of the two folders you will find the MSI file Citrix App Layering Agent.msi.

Citrix App Layering Agent unattended installation - contents temp folder MSI file

Copy the MSI to a different folder, because as soon as you close the installation wizard, the MSI will be deleted. After copying the MSI file you can cancel the installation wizard.

Before running the MSI file make sure that you have installed the prerequisites as described in the section above. Run the MSI as follows:

msiexec /i "C:\Temp\Citrix App Layering Agent.msi" /qn /l*v "C:\Logs\Install_CitrixAppLayeringAgent.log" PORT=8016 SKIP_ELM_REGISTRATION=1 TRANSFORMS="C:\Temp\CitrixAppLayeringAgentSkipELMRegistration.mst"

Note: make sure that the log directory exists before running the unattended installation to prevent errors!

The parsed MSI parameters are the same as for the executable file.

Note: when using the Citrix App Layering Agent.msi, the full path to the transform file is NOT required, as long as you keep the transform file in the same directory as the MSI file (e.g. TRANSFORMS="CitrixAppLayeringAgentSkipELMRegistration.mst").

The unattended installation method described in this paragraph skips the registration of the Citrix App Layering Agent to the ELM. The registration part is covered in the following paragraph.

Step 2: Registering with the App Layering appliance

The previous paragraph explains the installation of the Citrix App Layering Agent. In the manual installation wizard you are able to register the agent with the ELM directly, but this is not possible during an unattended installation. I explain this in detail in the section The Citrix App Layering Agent MSI does not enable registration parameters to be parsed during unattended installation.

The following command allows an administrator to register the ELM after installing the Citrix App Layering Agent:

"C:\Program Files (x86)\Citrix\Agent\Citrix.AppLayering.Agent.Service.exe" registerwithelm /elmaddress:"DNS or IP address" /user:"MyDomain\MyUser" /password:"MyPassword" /errorfile:"C:\Logs\ELMRegistrationErrorLog.log" /ignorecerterrors:true

Note: make sure that the log directory exists before running the command!

Let's analyze the various parameters:

  • registerwithelm - this parameter triggers the registration with the ELM.
  • /elmaddress:"DNS or IP address" - this parameters contains the DNS name or IP address of the ELM.
  • /user:"MyDomain\MyUser" - this parameter contains the user account with administrative permissions on the ELM.
  • /password:"MyPassword" - this parameter contains the password of the administrative user account.
  • /errorfile:"C:\Logs\ELMRegistrationErrorLog.log" - this parameter contains the path and filename (including file extension) where the error log should be created. Please be aware that this error log is only created in case of errors. If the registration process runs without errors, the error log is NOT created.
  • /ignorecerterrors:true - this parameter tells the executable to ignore any SSL/TLS errors.

The executable Citrix.AppLayering.Agent.Service.exe provides two default exit codes; 0 = success and 1 = error. In the following example I forced an error by omitting the parameter /ignorecerterrors:true. This lead to an SSL/TLS error. You can see that the exit code is correctly set to 1.

Citrix App Layering Agent unattended installation - ELM registration error

To see all available parameters, execute the following command: "C:\Program Files (x86)\Citrix\Agent\Citrix.AppLayering.Agent.Service.exe" /?.

The complete installation script below includes the ELM registration.

There are two manual ways to check if the registration was successful or not:

  1. On the Provisioning Server, open the log file C:\Program Files (x86)\Citrix\Agent\Logs\applayering.agent.log.Citrix App Layering Agent unattended installation - applayering.agent log file successful ELM registration
  2. In the App Layering console, go to System, Manage Appliance. Click on the information symbol next to Management Service. This opens the audit log. If successful, you will find the registration of your Provisioning Server there (the screenshot is from App Layering version 4.4, but looks the same in versions 4.5 to 4.8).Citrix App Layering Agent unattended installation - ELM audit log

Reference:

Complete installation script

The following script includes the installation and registration process of the Citrix App Layering Agent including detailed logging and error handling.

  • Created for: Citrix App Layering Agent 4.4 to 4.8 (may also work for older versions).
  • Supported operating systems: Windows Server 2008 R2 to Windows Server 2016 Build 1607
  • Tested on: Windows Server 2016 Build 1607

This script is based on my installation template. You can change the log directory and package name in lines 202 and 203. Also make sure to edit lines 213 to 216. These lines contain the variables required for the ELM registration (address, user account, password and location of the error log file).

One more thing. In the script, I parse the password of the administrative user account in plaint text. I do not recommend this for your production environment. For more information on how to secure passwords in a PowerShell script see Encrypting passwords in a PowerShell script.

From beginning to end, these are the steps involved for a successful installation:

  • Create an installation directory on the local computer or on a file share (UNC path). For example: C:\Temp\Citrix\App Layering Agent.
  • Create a subdirectory called Files.
  • Copy the file Citrix App Layering Agent.msi to the folder Files. You first have to extract the MSI file from the executable as described in one of the previous sections.
  • Download and copy the custom MST file CitrixAppLayeringAgentSkipELMRegistration.mst to the folder Files.
  • Copy the PowerShell script below to a new PS1 file (e.g. Install_CitrixAppLayeringAgent.ps1) and add this file to the root of your installation directory (not in the subdirectory Files).
  • Execute the PowerShell script: powershell.exe -file C:\Temp\Citrix\App Layering Agent\Install_CitrixAppLayeringAgent.ps1.

In case you get a security warning, set the execution policy to allow the script to run:
powershell.exe -executionpolicy bypass -file C:\Temp\Citrix\App Layering Agent\Install_CitrixAppLayeringAgent.ps1.

Note: you can use the same script for the unattended uninstallation of the Citrix App Layering Agent. Simply add the parameter uninstall, like this: powershell.exe -file C:\Temp\Citrix\App Layering Agent\Install_CitrixAppLayeringAgent.ps1 Uninstall

After installation, check the log files for detailed information. By default all log files are stored in the directory C:\Logs\Citrix_App_Layering_Agent (unless you changed the log directory and/or file name).

If you want to go one step further and create an SCCM package as well, please follow the step-by-step explanation in the article Deep dive creating SCCM packages for Citrix.

Explaining the MSI issue and the workaround (MST)

In this section, I go into more detail concerning the installation error and the MSI issues.

Public versus private MSI properties

Public properties are always completely written in UPPERCASE. Values of public properties can be changed/overridden by adding the property to the command line, by applying a transform, or by interacting with an authored user interface. Public property names cannot contain lowercase letters!

Private properties are used internally by the installer and their values must be entered into the MSI database by the author of the installation package. At least one character of the property name should be written in lowercase. A private property cannot be parsed on the MSI installer command line!

The Citrix App Layering Agent MSI does not skip ELM registration when running in unattended mode

An unattended installation ends in an error, because the MSI installer requires that the ELM registration is completed.

Citrix App Layering Agent unattended installation - installation error connecting to ELM

To be more precise, the custom action ConnectToElm requires this. Let us take a closer look at the contents of the MSI package. The custom action ConnectToElm is highlighted in the screenshot below. Also highlighted are the conditions under which the custom action is executed (UILevel<5 AND NOT Installed).Citrix App Layering Agent unattended installation - InstallShield custom action ConnectToELM condition original

Now, when checking the MSI properties, I found a very promising public property called SKIP_ELM_REGISTRATION. By default, this is set to 0. Citrix App Layering Agent unattended installation - InstallShield SKIP_ELM_REGISTRATION property

I hoped that adding this parameter to the MSI command line (and setting it to 1) would allow the unattended installation to finish without displaying an error. Unfortunately, this was not the case. The custom action ConnectToElm was still triggered and the error was still thrown.

Also the Skip button available during manual installation does not provide us with any useful public property (only a private property).

Citrix App Layering Agent unattended installation - installation wizard registration window skip button

Citrix App Layering Agent unattended installation - InstallShield wizard dialog skip button

This is why I had no other option than to create a transform file (*.MST) to fix this issue. The only thing I add to the transform file is an additional condition on the custom action ConnectToElm. As you can see in the screenshot below, I added the condition AND SKIP_ELM_REGISTRATION=0. Now, when the property SKIP_ELM_REGISTRATION is added to the MSI command line and set to 1, the ELM registration is actually skipped, thus preventing the error message.

Citrix App Layering Agent unattended installation - InstallShield custom action ConnectToELM condition new

The Citrix App Layering Agent MSI does not enable registration parameters to be parsed during unattended installation

In the previous paragraph we saw that the ELM registration cannot be skipped by default. Skipping the registration would not have been an issue at all if either the executable or the MSI file would have allowed for an unattended registration.
To get to the point, there are no (public MSI) properties available to register the Citrix App Layering Agent to the ELM during an unattended installation. Let me explain.

Let's take a look inside the MSI package and focus on the section Dialogs. This section contains the windows shown in the (manual) installation wizard. Here I found the dialog called ConfigureElmConnection. This dialog contains the registration window you see in the installation wizard when you execute it manually. Citrix App Layering Agent unattended installation - InstallShield Configure ELM Address private property

The windows contains three fields. When selecting each of the available fields, the corresponding property name of that field shows up in the column on the right. The properties for each of the three fields are:

  • Field "Address" -> MSI property "ConfigureElmAddress"
  • Field "User" -> MSI property "ConfigureElmUser"
  • Field "Password" -> MSI property "ConfigureElmPassword"

As explained above, this property contains lowercase characters, which means that this is a private property. And private properties cannot be parsed on the command line. So, even though there are properties available for each of the three data entries (ELM address, user and password), we cannot parse them.

This is the reason why I had to split the installation into two parts:

  1. The installation using the Citrix App Layering Agent.msi (skipping registration);
  2. The ("stand-alone") registration using the Citrix.AppLayering.Agent.Service.exe.

Conclusion

The installation of the Citrix App Layering Agent should be simple considering it is such a small component, but unfortunately it is not. I sincerely hope that Citrix will make the necessary improvements in future releases to allow for a less complicated unattended installation. For now, I hope this article is of some help to you.

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 App Layering Agent unattended installation

  1. Pingback: Scripting the complete list of Citrix components with PowerShell - Dennis Span

  2. Pingback: Detailed Change Log – Carl Stalhood

  3. Pingback: App Layering – Enterprise Layer Manager 4.5 – 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.