Citrix Director unattended installation with PowerShell

Posted on by

All Citrix products can be automated. This article covers the Citrix Director unattended installation and configuration with PowerShell and SCCM.

Change Log
01.09.2017: updated to Director 7.15 (from version 7.13).
17.12.2017: updated to Director 7.16. No major changes. Error correction in configuration script; the IIS attribute multipleSiteBindingsEnabled contained a spelling mistake (previously: multipleSiteBindingEnabled -> missing an ‘s’).
22.07.2018: updated the section Director Single Sign-on to include constrained delegation.
Table of Contents

Introduction

Before continuing with this article please be aware of the following:

  • The version of Citrix Director in this article is 7.16 (but all scripts work from version 7.13 and higher).
  • Director is part of the XenDesktop installation. The XenDesktop ISO file can be downloaded here:
    https://www.citrix.com/downloads/xenapp-and-xendesktop/product-software/xenapp-and-xendesktop-716.html
  • The installation and configuration scripts are designed for the following operating systems:
    • Microsoft Windows Server 2008 R2 SP1
    • Microsoft Windows Server 2012 R2
    • Microsoft Windows Server 2016
  • The installation and configuration scripts have been tested on the following operating systems:
    • Microsoft Windows Server 2008 R2 SP1
    • Microsoft Windows Server 2012 R2
    • Microsoft Windows Server 2016
  • The assumption is that you execute the example script in this article on a server that has been pre-installed with one of the aforementioned operating systems including all the latest hotfixes and .Net Framework 4.6.x. Also, you should at least have PowerShell 3.0 installed on the system, although I recommend using the latest version.

I strongly urge you to read the following articles:

  • Director 7.16 – by Carl Stalhood
    This article explains the manual installation of Director step-by-step (very detailed!). This article roughly follows the structure of Carl’s article.
  • Citrix Director – by George Spiers
    This article gives a very comprehensive overview of all the features of Director (very detailed!).

This article consists of three parts:

  • Part 1 focuses on the installation of the Windows Roles and Features;
  • Part 2 deals with the installation of Citrix Director;
  • Part 3 describes the configuration of Citrix Director.

Part 1: Install Windows Roles and Features

Before we install Citrix Director, I recommend installing some commonly used roles and features. Part of these components are optional, but .Net Framework 3.5.1 for Windows Server 2008 R2 and .Net Framework 4.5.x for Windows Server 2012 and higher are not. If .Net Framework is not installed, the installation of Director ends in an error. This error can be found in the Director’s log files IIS_Install.txt and XenDesktop Installation.txt: “Parent features must be enabled before this feature can be enabled. WCF-HTTP-Activation(45)”.

IIS and Remote Assistance
Please be aware that Internet Information Services (IIS) is a prerequisite for Director. The role Remote Assistance is required when you want to shadow users. Both of these components are installed automatically during the installation of Director. These components are NOT installed in this section of the article.

In this example, we will install the following features:

  • .Net Framework 3.5.1 (for W2K8R2 only)
  • .Net Framework 4.5.x (for W2K12 and W2K16 only)
  • Desktop experience (for W2K8R2 and W2K12 only)
  • Group Policy Management Console
  • Remote Server Administration Tools (AD DS Snap-Ins)
  • Remote Desktop Licensing Tools
  • Telnet Client
  • Windows Process Activation Service

You can remove or add any role or feature you need. Please be aware though that not all features can be installed at the same time. Some features need a reboot. After that, other features can be installed.

In PowerShell, roles and features are installed using the Add-WindowsFeature (Windows Server 2008 R2) or Install-WindowsFeature command (Windows Server 2012 and higher). For example:

Windows Server 2008 (R2):

Windows Server 2012 (R2):

Windows Server 2016:

In some cases, the names of the individual roles and features differ between the various operating systems:

  • .Net Framework:
    • Windows Server 2008 R2 only offers version 3.5.1 (Add-WindowsFeature command NET-Framework-Core).
    • Windows Server 2012 (R2) offers both the versions 3.5.1 and 4.5.x (Install-WindowsFeature command NET-Framework-Core and NET-Framework-45-Core), but I only install the 4.5.x version.
    • Windows Server 2016 only offers version 4.5.x (Install-WindowsFeature command NET-Framework-45-Core).
  • Desktop-Experience:
    This feature no longer exists as a separate item in Windows Server 2016. Let me clarify; when you use the full version of Windows Server 2016 (not the core/nano version), desktop experience is included out of the box.
  • Remote Desktop Licensing Tools:
    In Windows Server 2008 (R2), the abbreviation of this feature is called RSAT-RDS-Licensing. In Windows Server 2012 and higher, this feature is called RDS-Licensing-UI.

To establish the version of the running operating system, I use the following PowerShell command:

Complete script for installing Roles and Features

In case you use my installation template, this is what the complete script, including logging, looks like:

Execute the script as follows:
powershell.exe -file %Directory%\Install_Citrix_Director_Roles.ps1

In case you get a security warning, execute the script as follows:
powershell.exe -executionpolicy bypass -file %Directory%\Install_Citrix_Director_Roles.ps1

Log files are created in the directory C:\Logs\Citrix_Director_Roles, but you can change this to any directory you want (see lines 96 and 97).

Note:
The installation of the roles and features may require a reboot. The reboot is NOT part of the example script. You can either add it to the script yourself or if you use a deployment tool such as Microsoft SCCM, you can add a reboot task in the task sequence.

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.

Part 2: Install Citrix Director

The second part of this article focuses on the installation of the Citrix Director. So how do you start?

  • Create an installation directory on the local computer or a file share (UNC path). For example C:\Temp\Citrix\Director.
  • Create a subdirectory called Files.
  • Download and extract the XenDesktop 7.16 ISO file to the folder Files in the installation directory. The contents of the directory Files should now look like this:Citrix Director unattended installation - Source files
  • Copy the complete PowerShell script at the end of this paragraph to a new PS1 file (e.g. Install_CitrixDirector.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\DeliveryController\Install_CitrixDirector.ps1

The basic command line to install Director is as follows:

The installation file XenDesktopServerSetup.exe is located in the subfolder x64\XenDesktop Setup.

Complete script for installing Citrix Director

In case you use my installation template, this is what the complete script, including logging and error handling, looks like:

Execute the script as follows, for example:
powershell.exe -file C:\Temp\Citrix\Director\Install_CitrixDirector.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\Director\Install_CitrixDirector.ps1

Log files are created in the directory C:\Logs\Citrix_Director_(installation), but you can change this to any directory you want (see lines 187 and 188).

Part 3: Configure Citrix Director

The third part of this article focuses on the configuration of the Citrix Director.

If you have created the installation directory as described in part 2, you can continue as follows:

  • Make sure that your Citrix License Server is up and running (the latest version). The actual product licenses do not need to be installed yet. Please read the article Citrix License Server unattended installation with PowerShell and SCCM for more information on how to install and configure your Citrix License Server using PowerShell.
  • Make sure that you have at least one XenDesktop site up and running including the monitoring database. Citrix Director retrieves its information from this database. Please see the article Citrix Delivery Controller unattended installation with PowerShell and SCCM for more information on how to create and configure a XenDesktop site.
  • Copy the complete PowerShell script at the end of this part to a new PS1 file (e.g. Configure_CitrixDirector.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\Director\Configure_CitrixDirector.ps1

The configuration steps below are in direct alignment with the structure of Carl Stalhood’s article Director 7.16.

The following paragraphs describe each step in the configuration of Director individually. The complete PowerShell script at the end of this part includes all of these steps. When you use this script, you do not need to execute any of the individual steps described below!

Note:
Many of the customizations below involve modifying the web.config file, which by default is located in the folder C:\inetpub\wwwroot\Director. The settings in the web.config file can also be managed manually in the IIS manager. Go to IIS Manager \ You server \ Sites \ Default Web Site \ Director. In the right pane open Application Settings. All of these settings are read directly from the web.config file.

Add XenDesktop controller (replacing localhost)

To install Director on a dedicated server (= on a different server than a Delivery Controller), you need to enter the name of (only) one controller for each site. Director then automatically discovers all other controllers in the same site(s).

As per Citrix: “When Director is installed on the Controller, it is automatically configured with localhost as the server address, and Director communicates with the local Controller by default”. […] Specify only one Controller address for each site that you monitor. Director automatically discovers all other Controllers in the same Site and falls back to those other Controllers if the Controller you specified fails”.

The easiest way to add the controller in an automated procedure is to modify the file web.config, which by default is located in the folder C:\inetpub\wwwroot\Director. This file contains most of the local Director settings.

The line which needs to be modified is:

 <add key=”Service.AutoDiscoveryAddresses” value=”localhost” />

The value localhost needs to be replaced by the DNS name of one or more controllers (one controller per site). In the complete PowerShell script at the end of this part, the list of controllers is retrieved directly from the XenDesktop site database (using an SQL query). I use this same technique for configuring the XenDesktop site. Please make sure to customize the variables $DatabaseServer, $DatabaseServerPort, and $DatabaseName_Site in lines 128 to 130.

After retrieving the list of controllers, the script tries to add the first controller to the web.config file. Before adding the controller, a connection test is performed (using the PowerShell cmdlet Test-Connection) to see if the controller is up and running. If the test is successful, the controller is written to the web.config file. If an error occurs, the script continues with the following controller in the list. If none of the controllers are reachable, the script ends in an error.

If you want to take a closer look at the PowerShell code, please see lines 186 to 272 in the complete PowerShell script.

Note:
The web.config file is written in XML format, so it can be easily modified using only a few lines of PowerShell code. For example, this is the code for modifying the key Service.AutoDiscoveryAddresses in the XML node Configuration \ appSettings \ add:

$xml = [xml](Get-Content “C:\inetpub\wwwroot\Director\web.config”)
$node = $xml.configuration.appSettings.add
$node.SetAttribute(“Service.AutoDiscoveryAddresses”,”MyController.mydomain.com”);
# Add a new key/value
$xml.Save(“C:\inetpub\wwwroot\Director\web.config”)
Citrix Director unattended installation - Contents web.config file

The web.config file is stored in ANSI format, but in the first line of the file, the encoding is set to UTF-8. When modifying an XML file, PowerShell saves the file automatically as UTF-8. This seems to be no problem; the file is still interpreted correctly.

For more information on managing XML files using PowerShell, please read the Microsoft blog Update XML File using PowerShell.

Set Director Default Webpage

To make the Director website the default page within the IIS site, three steps are required:

  1. Create the file Director.html in the IIS root directory (default: C:\inetpub\wwwroot). You can use a different name other than Director.html. In this article, the redirection file is called Director.html.
  2. Remove the entry Director.html from the list of default documents in case it exists. This is an additional step to ensure that the next step works as planned.
  3. Add the value Director.html to the list of default documents and add the index number 0 (this puts Director.html to the top of the list).

Creating the Director.html is quite straightforward. All you need is the Set-Content PowerShell cmdlet, like this:

I have added the -Encoding parameter to ensure that the file is stored as a default ANSI file. The actual content is stored in the variable $Text. This variable is stored as a here-string. Here-strings are very useful in cases where the text is complex in terms of characters such as multiple quotation marks. A here-string allows you to write your text exactly the way you want it and PowerShell will interpret it literally. Please note that the here-string has to start from the first character of the line (without any indenting to the right). Otherwise, the here-string will fail.

The contents of the variable $Text is as follows:

There are two possible values for the window.location:

  • For HTTP connections: window.location=”/Director“;
  • For HTTPS connections: window.location=”https://MyURL/Director“;

In the complete PowerShell script at the end of this part, the Director URL is stored in the variable $DirectorURL (see line 129).

The next step is to check if Director.html is already part of the list of default documents. If yes, remove it. Removing it will make sure that the document is set to the first position in the list of default documents in the next step.

To check if the file is already present, I use the following PowerShell command:

To remove the file from the list in case it exists, I use the following PowerShell command:

The final step is to (once again) add the Director.html to the list of default documents and to put this file to the top of the list. The PowerShell command is as follows:

Please take note that, in the complete PowerShell script at the end of this part, the code looks slightly different. The reason for this is that I use variables for values such as Director.html as well as try\catch statements and lots of error handling and logging. You find the PowerShell code in lines 274 to 336.

Reference:

Director Spinning Circle (enable multiple IIS Site Bindings)

In case you use multiple IIS site bindings, you will need to modify the Director’s web.config file, which by default is located in the folder C:\inetpub\wwwroot\Director.

The line which needs to be modified is:

<serviceHostingEnvironment aspNetCompatibilityEnabled=”true”/>

The key multipleSiteBindingsEnabled must be added and set to true:

<serviceHostingEnvironment aspNetCompatibilityEnabled=”true” multipleSiteBindingsEnabled=”true” />

The PowerShell code is as follows:

The complete PowerShell script at the end of this part enables the binding of multiple sites. If you have not enabled this feature in IIS, please remove (or comment out) the corresponding lines (lines 338 to 363).

For more information on how to modify XML files using PowerShell, please see the following side note.

Reference:

Director Spinning Circle (enable IIS X-Frame-Options header)

In case you added an X-Frame-Options header in IIS, you will need to modify the Director’s web.config file, which by default is located in the folder C:\inetpub\wwwroot\Director.

The line which needs to be modified is:

 <add name=”X-Frame-Options” value=”SAMEORIGIN” />

The value SAMEORIGIN must be changed to ALLOW-FROM %URL%/director/default.html:

 <add name=”X-Frame-Options” value=”ALLOW-FROM http://localhost/director/default.html” />

You can also use the FDQN, for example, ALLOW-FROM http://director.home.local/director/default.html and you can use https of course.

The PowerShell code is as follows:

The complete PowerShell script at the end of this part configures the IIS X-Frame custom header. If you have not added an x-Frame-Options header in IIS, please remove (or comment out) the corresponding lines (lines 362 to 387).

For more information on how to modify XML files using PowerShell, please see the following side note.

Reference:

Pre-populate the domain field

It is possible to pre-populate the domain to the name of your choice. For this, it is necessary to modify the logon.aspx file, which by default is located in the folder C:\inetpub\wwwroot\Director. The user is still able to change the domain name if needed.

Line 450 needs to be extended with the variable Text=”MyDomain”. The original line is:

<asp:TextBox ID=”Domain” runat=”server” CssClass=”text-box” onfocus=”showIndicator(this);” 

The modified line is as follows:

<asp:TextBox ID=”Domain” runat=”server” Text=”MyDomain” CssClass=”text-box” onfocus=”showIndicator(this);” 

The file logon.aspx has to be stored in UTF-8 format!

The complete PowerShell script at the end of this part adds the domain name defined in the variable $DomainName in line 133 of the script.

If you want to take a closer look at the PowerShell code, please see lines 392 to 429.

Set the session time-out

By default, the idle time session limit of the Director is 245 minutes. This value can be changed in the Director’s web.config file, which by default is located in the folder C:\inetpub\wwwroot\Director.

The line which needs to be modified is:

<sessionState mode=”Custom” cookieless=”UseCookies” regenerateExpiredSessionId=”true” timeout=”245” cookieName=”DESKTOPDIRECTORSESSION” customProvider=”Citrix.Dmc.WebService.CustomSessionStateProvider”>

The PowerShell code is as follows:

The value of the key timeout can be changed to any setting you require. In the complete PowerShell script at the end of this part, the time-out is set at the default of 245 minutes. In case you would like to change it, simply change the value $SessionTimeOut in line 138 to the number of minutes you require. If you want to take a closer look at the PowerShell code, please see lines 428 to 445.

For more information on how to modify XML files using PowerShell, please see the following side note.

Disable SSL Check

On the login page of Director, the message You are not using a secure connection is displayed when you are not connecting through SSL. To prevent this message from appearing, the value UI.EnableSslCheck has to be set to false. This value can be changed in the Director’s web.config file, which by default is located in the folder C:\inetpub\wwwroot\Director.

The line which needs to be modified is:

<add key=”UI.EnableSslCheck” value=”false” />

The value has to be changed from true to false.

The PowerShell code is as follows:

In the complete PowerShell script at the end of this part, the value is set to false. If you want to take a closer look at the PowerShell code, please see lines 450 to 467.

For more information on how to modify XML files using PowerShell, please see the following side note.

Disable Activity Manager

As per Citrix: “By default, the Activity Manager in Director displays a list of all running applications for a user’s session. To protect the privacy of users and the applications they are running, you can disable the Applications tab from listing running applications.”

To disable the listing of running applications, the value UI.TaskManager.EnableApplications has to be set to false. This value can be changed in the Director’s web.config file, which by default is located in the folder C:\inetpub\wwwroot\Director.

The line which needs to be modified is:

<add key=”UI.TaskManager.EnableApplications” value=”false” />

The value has to be changed from true to false.

The PowerShell code is as follows:

In the complete PowerShell script at the end of this part, the value is set to false. If you want to take a closer look at the PowerShell code, please see lines 469 to 486.

For more information on how to modify XML files using PowerShell, please see the following side note.

Large Active Directory / Multiple Forests

As per Citrix: “When searching user accounts, the search process is either slow or it fails within Desktop Director”.

This may happen in large Active Directory environments or in an environment with multiple forests. The reason is that by default Director searches all the Global Catalogs in the Active Directory Forest using LDAP. In large environments, this query can take some time or even time out.

By adding the value Connector.ActiveDirectory.Domains and setting it to false, Director only searches the current domain. By default, this value is hidden and set to true. This means that you will not find this value in the web.config file; it has to be created. The default location of the web.config file is C:\inetpub\wwwroot\Director.

The line which needs to be created is:

<add key=”Connector.ActiveDirectory.ForestSearch” value=”false” />

The PowerShell code to add a new element is as follows:

In case Director should search more than the current domain, add the list of domains to the value Connector.ActiveDirectory.Domains. The line which needs to be changed is:

<add key=”Connector.ActiveDirectory.Domains” value=”(user),(server)” />

The new line is as follows:

<add key=”Connector.ActiveDirectory.Domains” value=”MyDomain1.com,MyDomain2.com” />

The PowerShell code is as follows:

Please take note that, in the complete PowerShell script at the end of this part, the above code looks slightly different, because I use variables, try\catch statements, and lots of error handling and logging. The list of custom search domains is stored in the variable $SearchableDomains (see line 142). If you want to take a closer look at the complete PowerShell code, please see lines 488 to 527.

For more information on how to modify XML files using PowerShell, please see the following side note.

Saved Filters (change location)

In Director you can create and save filters. By default, these filters are stored on the Director server itself in the directory C:\Inetpub\wwwroot\Director\UserData.

To change this path to a different directory (a network share for example), the value Service.UserSettingsPath in the Director’s web.config file needs to be changed. The web.config file is located in the folder C:\inetpub\wwwroot\Director by default.

The line which needs to be changed is:

<add key=”Service.UserSettingsPath” value=”..\UserData” />

The new line should be as follows:

<add key=”Service.UserSettingsPath” value=”\\MyServer\MyShare” />

The PowerShell code is as follows:

Please make sure that the directory you enter exists and that all administrators have the appropriate permissions.

If you want to take a closer look at the complete PowerShell code, please see lines 526 to 543 in the complete PowerShell script. The new directory for the saved filters is stored in the variable $SavedFiltersLocation (see line 137).

For more information on how to modify XML files using PowerShell, please see the following side note.

Director and Self-Service Password Reset (SSPR)

Installing the StoreFront Self-Service Password Reset (SSPR) tool on the same server as Director may break Director, unless:

The complete PowerShell script at the end of this part first checks if multiple IIS site bindings are enabled. The script reads the XML node configuration \ “system.serviceModel” \ serviceHostingEnvironment \ multipleSiteBindingsEnabled in the file C:\inetpub\wwwroot\Director\web.config. If this setting exists and is set to true, no further action is necessary. If this setting is missing or set to false, the script continues to remove port 8080 from the Default Web Site bindings using the Remove-WebBinding PowerShell cmdlet.

If you want to take a closer look at the PowerShell code, please see lines 548 to 582.

Director Grooming

By default in XenDesktop 7.16, historical data is groomed at either 8, 32, or 365 days, depending on your license. As per Citrix;

  • Trend reports of up to last year (365 days) are available on platinum-licensed sites.
  • Trend reports of up to the last month (31 days) are available on enterprise-licensed sites.
  • Trend reports of up to the last 7 days on non-platinum and non-enterprise licensed sites.

These values are configured on the Citrix Delivery Controller, not in Director. See the section Configure grooming settings in the article Citrix Delivery Controller unattended installation with PowerShell and SCCM on how to configure the grooming settings using PowerShell.

Director Single Sign-on

You can configure Director to support Integrated Windows Authentication (Single Sign-on). This setup involves some configurations in Active Directory and some on the local Director server. I recommend configuring Active Directory manually and automating the modifications on the local Director server.

Configure the following settings manually. In case you do not load balance Director, do the following:

  • Set up the http SPN for the Director server using the setspn.exe command: setspn -s http/MyURL MyDomain\MyDirectorServer. The variable MyURL has to be entered without the prefix http:// or https://.
  • Go to the properties of the computer account in Active Directory. On the tab Delegation, set Trust this computer for delegation to any service (Kerberos only).
  • Repeat the previous two steps for each non-load balanced Director server in your environment.

In case you load balance Director, you can ignore the previous manual configurations. Please configure the following:

  • Create a (service) account in Active Directory to be used for the IIS application pool identity;
  • Set up the http SPN for this service account using the setspn.exe command: setspn -s http/MyURL MyDomain\MyServiceAccount. The variable MyURL has to be entered without the prefix http:// or https://.
  • Go back to the service account in Active Directory. A new tab called Delegation is now available. Set delegation to Trust this user for delegation to any service (Kerberos only).

In case your security department is not too happy with the delegation Trust this user for delegation to any service (Kerberos only) (circled in red in the image below), it is possible to narrow it down to specific users or computers (so-called constrained delegation). Select Trust this computer for delegation to specified services only (circled in orange in the image below). Make sure that Use Kerberos only is selected. Click add to add the computer accounts that host the Director service.

The example below also applies when configuring delegation on the user (service) account instead of the computer account.

Citrix Director unattended installation - Choose unconstrained or constrained delegation

Click the Users or Computers button and add the Director servers:

Citrix Director unattended installation - Constrained delegation - select computer objects

Locate and select the http (Director) service.

Citrix Director unattended installation - Constrained delegation - add services

Repeat these steps for each Director server.

Note: I did not fully test the scenario with constrained delegation. It may be that more services need to be added.

Now we can continue to configure the local Director server. In total, we need to configure four IIS settings:

Enable Windows authentication on the Director site
The PowerShell command is as follows:

Disable anonymous authentication on the Director site
The PowerShell command is as follows:

Enter the application pool credentials (required when load balancing multiple Director servers)
The PowerShell command is as follows:

The identity type 3 refers to a “specific user account”. Please see the article Process Model Settings for an Application Pool <processModel> for more information. To manually add a password using the IIS Manager, open the IIS Manager and go to YourServer \ Application Pools \ Director. With a right-mouse-click on Director, go to Advanced Settings. In the section Process Model, click on Identity. Select the button with the three dots, choose Custom Account, and add your service account (e.g. MyDomain\MyServiceAccount).

Citrix Director unattended installation - Set application pool credentials

Enable the use of the ‘useAppPoolCredentials’
In the previous step, we entered the service account in the application pool credentials. However, these credentials cannot be used right away. You see, by default in IIS, Kerberos service tickets are handled by the local machine. The local machine however has no permission to decrypt these tickets. By enabling the use of application pool credentials, we allow IIS to use the service account to decrypt Kerberos tickets from the clients. For more information, please see the following two articles: Internet Information Services (IIS) 7.0 Kernel Mode Authentication Settings and Configuring Kerberos Authentication on IIS Website. By default, certain sections of the Default Web Site in IIS are locked and configuration changes cannot be made. We first have to unlock the section system.webServer / security / authentication / windowsAuthentication. The PowerShell code is as follows:

Reference: https://stackoverflow.com/questions/5717154/programmatically-unlocking-iis-configuration-sections-in-powershell

Now we can continue to enable the use of application pool credentials. This is the PowerShell command:

It is not necessary to disable the Kernel mode authentication if you configure the WindowsAuthentication element on the application pool (reference: Understanding Kernel mode authentication in IIS 7).

Securing password:
There seems to be a security issue concerning passwords in IIS. According to the following article, passwords are encrypted in the IIS application pool configuration file when they are set using the IIS Manager or the executable AppCmd.exe:

“To avoid storing unencrypted password strings in configuration files, always use AppCmd.exe or IIS Manager to enter passwords. If you use these management tools, the password strings will be encrypted automatically before they are written to the XML configuration files. This provides better password security than storing unencrypted passwords”.

The configuration file for the application pools is located here:

C:\Windows­\System32­\inetsrv­\config­\applicationHost­.config.

When you open the file after manually configuring the password, you see an encrypted string (as far as you can call this truly “encrypted”).

Citrix Director unattended installation - Application pool encrypted password

When you use the PowerShell command, the password is stored in plain text. However, as soon as you view or export the application pool settings, the password is written in plain text, even if the password was stored encrypted:

  • View settings: %SystemRoot%\System32\inetsrv\APPCMD list apppool /text:*
  • Export settings: %SystemRoot%\System32\inetsrv\APPCMD list apppool “Director” /config /xml > C:\MyApppoolExport.xml

This is a security bug in IIS and cannot be prevented (as far as my knowledge goes).

If you do not want to store your password in plain-text format in your PowerShell script, please see the article Encrypting passwords in a PowerShell script.

If you want to take a closer look at the complete PowerShell code, please see lines 592 to 658 in the complete PowerShell script. The user name and password for the application pool identity are stored in the variables $AppPoolUserName and $AppPoolPassword (see lines 126 to 127).

Multiple XenDesktop Sites

Adding an XenDesktop controller to Director is covered in the section Add XenDesktop controller (replacing localhost). You can re-use the PowerShell code to add multiple controllers, or you can extend the code to check multiple SQL databases and/or multiple SQL servers.

Please note that if you want to monitor multiple XenDesktop sites using one Director, only one controller per site should be entered in the web.config file. Do not enter more than one controller; Director automatically discovers the other controllers in the site.

Generate SNMP traps

SNMP traps are generated by the Delivery Controller, not Director. By default, the cmdlets are not present on a stand-alone Director server (e.g. Get-MonitorNotificationSnmpServerConfiguration).

Please see the following Citrix article on how to configure SNMP traps: Alerts and notifications.

SCOM Integration

Since Director 7.7, it is possible to aggregate SCOM alerts in the Director console. The way how to enable this is to:

  • Enable WinRM (if not already enabled)
    Remote management (WinRM) is a prerequisite. WinRM is enabled by default on operating systems from Windows Server 2012 and higher. On a server running Windows Server 2008, WinRM has to be explicitly enabled.
  • Add the SCOM server to the list of trusted hosts (WinRM)
  • Configure SCOM for Director
    Executing the command C:\inetpub\wwwroot\Director\tools\DirectorConfig.exe /configscom to configure SCOM for Director.
    The DirectorConfig.exe command requires some input, such as the name of your SCOM server and the ports to use for WinRM (default: 5985 for HTTP and 5986 for HTTPS). The DirectorConfig.exe then continues to do the following:

    • Add new entries to the web.config file (default location: C:\inetpub\wwwroot\Director):
      • <add key=”Connector.SCOM.ManagementServer” value=”MySCOMServer.mydomain.com” />
      • <add key=”Connector.SCOM.Identity” value=”User” />
      • <add key=”Connector.SCOM.WSManTransport” value=”http” />
      • <add key=”Connector.SCOM.WSManPort” value=”5985” />
    • On Windows Server 2008 R2:
      Install ASP.NET (4.x) without changing existing web applications to use this version of ASP.Net. The command which is executed is C:\Windows­­\Microsoft.NET­­\Framework­­\v4.0.30319­\­aspnet_regiis.exe -ir is used.
    • On Windows Server 2012 and higher:
      Install several Windows features using the Microsoft Deployment Image Servicing and Management tool (DISM.exe). The exact command executed by the DirectorConfig.exe is: “C:\Windows\system32\Dism.exe” /Online /Enable-Feature /FeatureName:IIS-NetFxExtensibility45 /FeatureName:IIS-ASPNET45 /FeatureName:WCF-HTTP-Activation45

Reference: Citrix article Alerts and notifications (in the section SCOM alerts).

Note:
So how can I be so sure which features the DirectorConfig.exe installs? Well, in the verbose output of the DirectorConfig.exe (on a W2K12 and W2K16 server), I saw that the tool DISM.exe is used. By default, DISM.exe writes all output to a log file. This log file can be found here: C:\Windows\Logs\DISM\dism.log. After searching the log file for DISM.EXE: Executing command line I found the exact command line syntax.

Citrix Director unattended installation - DirectorConfig.exe SCOM configuration

On a W2K8R2 server, DISM.exe is not used. Here, the executable aspnet_regiis.exe is used. The exact command executed by the DirectorConfig.exe is C:\Windows­\Microsoft.NET­\Framework­\v4.0.30319\­aspnet_regiis.exe -ir.

Now that we know exactly what needs to be configured, we can start automating the procedure.

Enable WinRM

First, we will check if WinRM is enabled; if not, it will be enabled. The PowerShell code is as follows:

The PowerShell command Enter-PSsession -computername localhost can be used to test if WinRM is up and running. To enable WinRM use the command Enable-PSRemoting -Force.

Reference: Microsoft article Enable-PSRemoting.

Add SCOM server to trusted hosts (WinRM)

The next step is to add the SCOM server to the list of WinRM trusted hosts, but first, we have to check the list of existing trusted hosts. I use the following PowerShell command for this:

The variable $ExistingTrustedHosts now contains the list of existing hosts. In case no trusted hosts exist, this variable is empty.
Now we will check the contents of the variable $ExistingTrustedHosts to verify if the SCOM server is perhaps already included in the list of trusted hosts:

If the SCOM server is not included in the list of trusted hosts, it is added in the next step:

Besides the SCOM server, all previously existing trusted hosts are added as well. Without this, adding the SCOM server would overwrite all pre-existing values.

Modify the web.config file

The web.config file, by default located in the directory C:\inetpub\wwwroot\Director, needs to be modified. The following PowerShell code adds the required four lines with the SCOM configuration:

Since these lines are completely new, a new XML element has to be created in the existing node Configuration \ appSettings. The same function is executed four times; one for each of the four lines. The last line saves the new elements to the XML file (the web.config file).

Install ASP.NET (on Windows Server 2008 R2)

The last thing the DirectorConfig.exe does is to install ASP.NET using the executable aspnet_regiis.exe (default location: C:\Windows­\Microsoft.NET­\Framework­\v4.0.30319) and the parameter -ir.

The following PowerShell code shows how to execute the aforementioned command using PowerShell.

Install Windows features (on Windows Server 2012 and higher)

The last thing the DirectorConfig.exe does is install three Windows features. The following PowerShell code shows how to add a feature using PowerShell and the DISM.exe.

The main command line in the above example is: Dism.exe /Online /Enable-Feature /NoRestart /FeatureName:$FeatureName

If you want to take a closer look at the complete PowerShell code, please see lines 673 to 805 in the complete PowerShell script. The SCOM server name, SCOM protocol, and SCOM port are stored in the variables $SCOMServer, $SCOMProtocol, and $SCOMPort (see lines 138 to 140). The script determines the version of the operating system automatically. It then executes the aspnet_regiis.exe or DISM.exe command depending on the version.

For more information on how to modify XML files using PowerShell, please see the following side note.

Complete script for configuring Citrix Director

In case you use my installation template, this is what the complete script, including logging and error handling, looks like.

Important!
Please be aware that the complete script includes all of the above-mentioned configurations. In most cases, you will only need a few of these. Therefore, I strongly recommend you go through the script and remove or comment-out the sections you do not need. The script follows the same structure as Part 3 in this article.

Please make sure to customize the variables from line 126 to line 144 to your requirements!

Note: in some cases, the database connection (lines 214 to 218) may end in an error (“cannot open database”). This can happen if you use the standard SQL port 1433. In this case, please remove the variable $DatabaseServerPort (including the preceding comma) from line 212. The credit (and my thanks) for finding this error goes to Thorsten Enderlein (@endi24).

Execute the script as follows, for example:
powershell.exe -file C:\Temp\Citrix\Director\Configure_CitrixDirector.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\Director\Configure_CitrixDirector.ps1

Log files are created in the directory C:\Logs\Citrix_Director_(configure), but you can change this to any directory you want (see lines 103 and 104).

Conclusion

This concludes this article on the Citrix Director unattended installation. You can customize the scripts in this article in any way you see fit.

As stated at the beginning of this article, I strongly recommend you read the following two articles:

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

If you have any questions or recommendations please leave a comment below. Happy scripting!

20 thoughts on “Citrix Director unattended installation with PowerShell”

  1. Pingback: Citrix Director – JGSpiers.com

  2. Pingback: Detailed Change Log – Carl Stalhood

  3. Pingback: Director 7.14 – Carl Stalhood

  4. Pingback: Site Updates – June 2017 – Carl Stalhood

  5. Pingback: Director 7.15 – Carl Stalhood

  6. Pingback: Citrix Director – Digital Cloud Zone

  7. Pingback: EUC Weekly Digest – June 24, 2017 – Carl Stalhood

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

  9. Pingback: Director 7.17 – Carl Stalhood

  10. Pingback: Director 7.18 – Carl Stalhood

  11. Pingback: Director 1808 – Carl Stalhood

  13. These posts are great and invaluable to me right now! It looks like Citrix has updated their Director installation media for the latest version, 7 1808_2.

    Reply ↓

    • Thanks a lot David! I am happy that my articles are of some help to you. What did you mean with the remark concerning the Director installation? I know I have to update my article to include the latest version of Director, but did something change in such a way the information in my article was incorrect or incomplete?

      Reply ↓

  14. Pingback: Director 1811 – Carl Stalhood

  15. Pingback: Citrix Director 1906 – Carl Stalhood

  16. Pingback: Director 7.16 – Carl Stalhood

  17. Pingback: Citrix Director 1912 LTSR – Carl Stalhood

  18. Pingback: Citrix Director 2203 LTSR – Carl Stalhood

Leave a Reply

Your email address will not be published. Required fields are marked *

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