Citrix Delivery Controller unattended installation with PowerShell and SCCM

The installation and configuration of all Citrix products can be automated. This article covers the Citrix Delivery Controller unattended installation with PowerShell and SCCM. Also included is the unattended creation and configuration of the XenDesktop site.

Change Log
22.05.2017: Updated create/join site routine (read SQL site database directly).
23.05.2017: Updated to version 7.14 (previously 7.13). All settings still apply to version 7.13 as well.
30.08.2017: Updated to version 7.15 (previously 7.14 / 7.14.1). All settings still apply to version 7.13 and 7.14 / 7.14.1 as well. One small change is that Local Host Cache is now enabled by default and Connection Leasing disabled by default. This applies to new XenDesktop sites only (not site upgrades).
Table of Contents

Introduction

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

  • The version of Citrix Delivery Controller in this article is 7.15.
  • The software can be downloaded here:
    https://www.citrix.com/downloads/xenapp-and-xendesktop/product-software/xenapp-and-xendesktop-715.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 script have been tested on the following operating systems:
    • Microsoft Windows Server 2008 R2 SP1
    • Microsoft Windows Server 2016
  • The assumption is that you execute the example script in this article on a server which has been pre-installed with one of the aforementioned operating systems including all latest hotfixes.

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 the Citrix Delivery Controller;
  • Part 3 describes the configuration of the XenDesktop site.
Note:
Some of the configuration routines in this article are based on the Citrix article XenDesktop 7 Site Creation via PowerShell from 2013.

Part 1: Install Windows Roles and Features

Before we install the Citrix Delivery Controller software, I recommend to install some commonly used roles and features.

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 do 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:

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), this 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 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_CitrixDeliveryControllerRoles.ps1

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

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

Note:
The installation of the roles and features requires 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 Delivery Controller

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

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

During installation, the built-in firewall is configured automatically (the MSI parameter /configure_firewall takes care of this). The parameter /nosql prevents the installation of a local SQL database. As per Citrix:

[The /nosql parameter] Prevents installation of Microsoft SQL Server Express on the server where you are installing the Controller. If this option is omitted, SQL Server Express is installed for use as the Site database. (This option has no effect on the installation of SQL Server Express LocalDB used for Local Host Cache.)

The basic installation command line (included in the complete PowerShell script at the end of this paragraph) is as follows:

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

For more information on the command line options for the XenDesktopServerSetup.exe, please refer to the XenDesktop 7.15 knowledge base article Install using the command line.

Complete script for installing the Citrix Delivery Controller

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:
powershell.exe -file C:\Temp\Citrix\DeliveryController\Install_CitrixDeliveryController.ps1

In case you get a security warning, execute the script as follows:
powershell.exe -executionpolicy unrestricted -file C:\Temp\Citrix\DeliveryController\Install_CitrixDeliveryController.ps1

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

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.

Note:
Before you continue with part 3, first reboot the server, otherwise importing the XenDesktop module ends in an error. 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.

Part 3: Create and configure or join the XenDesktop site

The third part of this article focuses on the creation and configuration of the Citrix XenDesktop site. In this part, the three main XenDesktop databases are created as well as the XenDesktop site. Also, the first delivery controller is added to the new site. All other servers, except for the first one, are joined to the site.

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.
  • XenDesktop requires three databases. In order to create these databases, you need a Windows (Active Directory) account with the appropriate SQL permissions (securityadmin or sysadmin). The script below assumes that the currently logged on administrator has sufficient permissions.
  • Copy the complete PowerShell script at the end of this paragraph to a new PS1 file (e.g. Configure_CitrixXenDesktopSite.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\Configure_CitrixXenDesktopSite.ps1

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.

Create databases

The first step when creating a XenDesktop site is to create the required databases (site, logging and monitoring). Prepare the following input parameters (required in lines 123 to 128 in the complete PowerShell script):

  • $SiteName
    The name of your XenDesktop site. For example: “MySite”.
  • $DatabaseServer
    The name of your SQL server or SQL server instance (e.g. “SQLServer1” or “SQLServer1\SQLCTX01”).
  • $DatabaseName_Site
    The name for the site database. For example: “CTX_Site_DB”.
  • $DatabaseName_Logging
    The name for the logging database. For example: “CTX_Logging_DB”.
  • $DatabaseName_Monitoring
    The name for the monitoring database. For example: “CTX_Monitoring_DB”.
  • $DatabaseCredentials -> this parameter is not included in the complete PowerShell script. Please add if required (see the section Handling Passwords at the end of the article).
    The service account (AD user) with the required SQL permissions including password. This PowerShell variable needs to be constructed using the PSCredential object (New-Object System.Management.Automation.PSCredential). For more information please see the article Encrypting passwords in a PowerShell script.

A XenDesktop site requires the following three databases:

  • Site database
  • Logging database
  • Monitoring database

The first step when creating a new site is to create these databases using the following PowerShell commands:

The above commands require dbcreator permissions on the SQL server (https://support.citrix.com/article/CTX127998).

The complete PowerShell script at the end of this part includes the creation of the databases and the site (as well as joining servers) including detailed logging and error handling.

Create or join XenDesktop site

If the current server is the first one in the site, the first action is to create all service-specific database schemas and to add this server as the first controller to the site. Any other server is joined to the site.
For both creating and joining, securityadmin permissions on the SQL server are required (https://support.citrix.com/article/CTX127998).

The PowerShell command to create the site, and to subsequently add the first controller to the site, is as follows:

The basic command to join a server to an existing site is:

In the complete PowerShell script at the end of this paragraph, a custom routine is used to determine if the site is up-and-running. Using PowerShell and SQL queries, this information is read directly from the site database.

Citrix Delivery Controller unattended installation with PowerShell and SCCM - Read site database directly using PowerShell and SQL queries

When joining a controller to the site, an existing controller has to be parsed in one of the required parameters (Add-XDController -SiteControllerAddress $Controller). The complete PowerShell script handles this automatically. It reads all available controllers directly from the site database and uses the first one it finds to join the controller. Should the joining fail for some reason, the second available controller is used until there are no more controllers or no more errors.

Connect to the Citrix License Server

The next step is to connect to your Citrix License Server. Prepare the following input parameters (required in lines 129 to 133 in the complete PowerShell script):

  • $LicenseServer
    The name of your license server, for example: mylicserver.mycompany.com.
  • $LicenseServerPort
    The port number for the initial contact, for example 27000 (this is the default value)
  • $LicensingModel
    The license model. Possible values are UserDevice and Concurrent.
  • $ProductCode
    The product code. Possible values are XDT (for XenDesktop) or MPS (for the XenDesktop 7.x App Edition).
  • $ProductEdition
    The product edition. Possible values are STD (Standard), ENT (Enterprise) or PLT (Platinum). 

The first action is to set the license server address ($LicenseServer) and the port number ($LicenseServerPort). In case you change the port number, please do not forget to modify your firewall rules if needed.

The “-Force” parameter makes sure that the server and port combination are NOT checked. This is handy in case your license server is temporarily offline or if you are installing your delivery controller before installing your license server.

The next step is to set the licensing model, product code and product edition:

The last step is to add the hash value of the self-signed security certificate, used to enable SSL communication, to the site.

For more information regarding the self-signed certificate read the section Install Citrix License Server in the article Citrix License Server unattended installation with PowerShell and SCCM.

The complete PowerShell script at the end of this part includes the configuration of the Citrix license server including detailed logging and error handling.

Add administrators

You may want to add some administrators to your site. Two steps are needed to create and configure a new administrator. First, the administrator has to be created and secondly the role and scope need to be set. For more information on how to create and configure administrators, please refer to the following Citrix article: https://docs.citrix.com/en-us/xenapp-and-xendesktop/7-15-ltsr/secure/delegated-administration.html.

Prepare the following input parameters (required in lines 134 to 136 in the complete PowerShell script):

  • $AdminGroup
    The name of the Active Directory user or group, for example MyDomain\CTXAdmins.
  • $Role
    The role to assign to the new XenDesktop administrator. The following built-in roles are available:

    • Full Administrator
    • Read Only Administrator
    • Help Desk Administrator
    • Machine Catalog Administrator
    • Delivery Group Administrator
    • Host Administrator
  • $Scope
    The scope (the objects) to which the permissions (defined in the role) apply. There is only one built-in role, namely All.

The following PowerShell command creates a new XenDesktop administrator:

The following command assigns the role and scope defined in the variables in the beginning of this paragraph:

The complete PowerShell script at the end of this part includes the creation of a XenDesktop administrator including detailed logging and error handling.

Configure grooming settings

The grooming (retention) settings refer to the monitoring settings. For example, the grooming settings include how long data is kept in your monitoring database. The longer data is kept, the larger the database will grow.

Use the following PowerShell commands to check the current configuration of the grooming settings:

The default grooming settings for a XenDesktop 7.15 site with platinum licenses are as follows:

Citrix Delivery Controller unattended installation with PowerShell and SCCM - Default grooming settings XenDesktop Platinum (Get-MonitorConfiguration)

As you can see in the screenshot, there are other settings besides retention days.

In this example, we increase the days that data is stored in the monitoring database for the following data types:

  • GroomApplicationInstanceRetentionDays
  • GroomDeletedRetentionDays
  • GroomFailuresRetentionDays
  • GroomLoadIndexesRetentionDays
  • GroomMachineHotfixLogRetentionDays
  • GroomNotificationLogRetentionDays
  • GroomResourceUsageDayDataRetentionDays
  • GroomSessionsRetentionDays
  • GroomSummariesRetentionDays

Prepare the following input parameter (required in line 137 in the complete PowerShell script):

  • $GroomingDays
    The number of days you want to monitoring data to be saved in the database, for example 365 days.

The PowerShell command is as follows:

The complete PowerShell script at the end of this part includes configuring the grooming settings including detailed logging and error handling.

Allow trusted XML request

To allow pass-through authentication, the Delivery Controller needs to trust XML requests sent by the StoreFront server. In a XenDesktop 7.15 site, these XML requests are not trusted by default.

Use the following PowerShell commands to check the configuration:

Check the setting TrustRequestsSentToTheXmlServicePort  and see that it is set to False.

Citrix Delivery Controller unattended installation with PowerShell and SCCM - Trusted XML Requests disabled

To enable trusted XML requests, we need to change this setting to True. The following PowerShell command does just that:

The complete PowerShell script at the end of this part includes enabling trusted XML requests including detailed logging and error handling.

Disable Connection Leasing and Enable Local host Cache

Note (30.08.2017): from Citrix XenDesktop version 7.15, Connection Leasing is disabled by default and Local Host Cache is enabled by default. Please be aware that this applies to new sites only! If you are upgrading to XenDesktop 7.15 from an existing, pre-XenDesktop 7.15, site, the settings of the existing site are used as-is.

Connection Leasing is the pre-XenDesktop 7.12 version of Local Host Cache. In XenDesktop 7.12, Local Host Cache was introduced. Local Host Cache is preferred to Connection Leasing. In a pre-XenDesktop 7.15 site, Connection Leasing is enabled by default and Local Host Cache is disabled by default. Use the following PowerShell commands to check the active configuration:

The screenshot below shows the default settings in XenDesktop 7.15.Citrix Delivery Controller unattended installation with PowerShell and SCCM - Local Host Cache enabled by default, Connection Leasing disabled by default (Get-BrokerSite)The following PowerShell commands disable Connection Leasing and enable Local Host Cache:

In the complete PowerShell script at the end of this part, Connection Leasing is disabled and Local Host Cache enabled. The script includes detailed logging and error handling. It is no problem to execute this script on a new XenDesktop 7.15 site where these settings are already configured correctly.

Disable CEIP

The Customer Experience Improvement Program (CEIP) can be disabled in Citrix Studio:Citrix Delivery Controller unattended installation with PowerShell and SCCM - Disable CEIP in Studio

The same can be accomplished with the following PowerShell command:

Please note that I am not stating that CEIP should be disabled! I am only showing you how to do it in case you want to.

The complete PowerShell script at the end of this part includes the disabling of CEIP including detailed logging and error handling.

Complete script for configuring the XenDesktop site

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

Handling passwords

The complete PowerShell script below assumes that the user executing the script has all necessary permissions (see the Citrix article Database Access and Permission Model for XenDesktop).

If this is not the case, you will have to make the following modifications:

  • Lines 192, 209 and 226 – add credentials to the New-XDDatabase cmdlet:
    New-XDDatabase -AdminAddress $ComputerName -SiteName $SiteName -DataStore Monitor -DatabaseServer $DatabaseServer -DatabaseName $DatabaseName_Monitoring -DatabaseCredentials $PSCredObject -ErrorAction Stop | Out-Null
  • Lines 248 and 294 – modify the SQL connection string:
    $SQL_ConnectionString = “Server=$DatabaseServer,$DatabaseServerPort;­­Database=­­$DatabaseName_­Site­;User id=­%DOMAIN%\USERNAME%;­Password=­%Password%;­Trusted_Connection=true;
  • Lines 325 –  add credentials to the Add-XDController cmdlet:
    Add-XDController -SiteControllerAddress $Controller  -DatabaseCredentials $PSCredObject | Out-Null
    You can also assign the database credentials for each of the databases individually (using the parameters -LoggingDatabaseCredentials, -MonitorDatabaseCredentials and -SiteDatabaseCredentials). For more information please enter the following command in a PowerShell console:

The security credentials have to presented in the form of a PSCredential object. Please the article Encrypting passwords in a PowerShell script for more information how to create such an object.

No credentials are needed for the New-XDSite cmdlet, since the cmdlet New-XDDatabase already adds the local server to the security permissions of the SQL database.

Please make sure to customize the variables from line 123 to line 137 to your requirements!

Note: in some cases the database connection (lines 248 to 251) 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 248. The credit (and my thanks) for finding this error goes to Thorsten Enderlein (@endi24).

Execute the script as follows:
powershell.exe -file C:\Temp\Citrix\DeliveryController\Configure_CitrixXenDesktopSite.ps1

In case you get a security warning, execute the script as follows:
powershell.exe -executionpolicy unrestricted -file C:\Temp\Citrix\DeliveryController\Configure_CitrixXenDesktopSite.ps1

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

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.

Conclusion

This article covers most initial settings. Of course you can automate many more things, such as creating machine catalogs or delivery groups. Some recommended settings for a XenDesktop site, for example enabling Read-Committed Snapshot on the XenDesktop databases in large environments, is not covered in this article.

I strongly recommend to read Carl Stalhood’s very detailed installation procedure for XenDesktop 7.15: http://www.carlstalhood.com/delivery-controller-7-15-ltsr-and-licensing/.

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.

You can customize the scripts in this article in any way you see fit. If you have any questions or recommendations please leave a comment below. Happy scripting!

Share this post:
Dennis Span on EmailDennis Span on LinkedinDennis Span on Twitter
Dennis Span
Dennis Span
Senior Citrix Architect

Dennis Span works as a Senior Citrix Architect for a large insurance company in Vienna, Austria. In 2017, Dennis became a Citrix Technology Advocate. Besides his interest in virtualization technologies, he loves spending time with his family as well as snowboarding, playing basketball and rowing. He is fluent in Dutch, English and German, speaks advanced Slovak and some Spanish and French.


12 thoughts on “Citrix Delivery Controller unattended installation with PowerShell and SCCM

  1. Pingback: Detailed Change Log – Carl Stalhood

  2. Pingback: Delivery Controller 7.13 and Licensing – Carl Stalhood

  3. Pingback: EUC Weekly Digest – April 8, 2017 – Carl Stalhood

  4. Hi Dennis,

    I’m new to powershell scripting. These look great and will go thru them.
    Question, do have further ones like script for the other components, Studio, Storefront and XenApp Servers as opposed to XenDesktop? Any insight greatly appreciated.

  5. Hi Jeff,

    First of all thanks for using my scripts! I am currently working on a number of articles concerning the installation and configuration of all major Citrix products. Please see my site map for everything that I have written so far: http://dennisspan.com/sitemap

    At the moment I am working on Citrix Provisioning Server. I hope to have it finished by the end of the week. Components for which I still need (and want) to write are StoreFront, Director and XenServer. These will follow in the upcoming weeks.

    Perhaps I may also point you to the following article: http://dennisspan.com/scripting-the-complete-list-of-citrix-components-with-powershell/. This one includes all (smaller) Citrix components and plugins and can be quite useful.

    If you want to stay informed on any new stuff I write you can follow me on Twitter (@dennisspan) or LinkedIn.

    Bye,

    Dennis

  6. Pingback: Delivery Controller 7.14 and Licensing – Carl Stalhood

  7. Hi Dennis,

    I’m always getting this message in the logfile:
    23-06-2017 10:06:18 I – Check if the XenDesktop site is configured and retrieve the site version number
    23-06-2017 10:06:33 E – An error occurred trying to retrieve the site and site version (error: Exception calling “Open” with “0” argument(s): “A network-related or instance-specific error occurred while establishing a connection to SQL Server. The server was not found or was not accessible. Verify that the instance name is correct and that SQL Server is configured to allow remote connections. (provider: TCP Provider, error: 0 – The remote computer refused the network connection.)”)

    Do you have an idea what could be wrong?

    Thanks

    Regards Walter

    • Hi Walter,

      First of all, thanks for using my scripts! 🙂

      According to the error, the SQL server was not found. Did you specify the server name (+ instance) correctly in the variable ‘$DatabaseServer’ in line 124? If you do not use instance names, the server name is something like “MySQLServer.mydomain.com”. If you use instances, you have to add this instance to the server name like this: “MySQLServer.mydomain.com\\MyInStanceName”. Also, in line 125 you have to specify the port (variable $DatabaseServerPort) . Did you enter the correct one? By default SQL uses port 1433, but you may use a different port in your environment. You can use the telnet command to check if your SQL server is reachable, e.g.: telnet MySQLServer.mydomain.com 1433. Another issue may be the local or remote firewall. Again, use the telnet command to see if you can reach your SQL server. And yet another issue may be that the service “SQL Server” on your SQL server is not running. Please check this as well.

      Kind regards,

      Dennis

  8. Hi Dennis,

    thanks for the quick answer. SQL Server was not listening on 1433 Port. Need to change TCP dynamic Port to specific port (in SQL Server Configuration Manager) and reboot SQL Service. Now it works 😉

    Thank you

    Regards Walter

  9. Pingback: Delivery Controller 7.15 LTSR and Licensing – Carl Stalhood

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

Leave a Reply

Your email address will not be published.

*