Author's note: a big thanks to Andreas Kinzl, a true SCCM guru, for reviewing this post and making some excellent suggestions.
The installation and configuration of all Citrix components can be automated with the help of PowerShell and Microsoft System Center Configuration Manager. The first step is to create the required SCCM packages. If you are new to this, the task may seem daunting. But do not worry, this article, Deep dive creating SCCM packages for Citrix, will guide you step-by-step.
In summary, when automating your environment using SCCM you have to go through the following steps:
- Create SCCM packages for all your installations and configurations
- Test your packages
- Create a major task sequence to automatically install a Citrix infrastructure server (e.g. Delivery Controller, StoreFront) or to create a worker image (e.g. for Hosted Shared based on Windows Server 2016 or a VDI image based on Windows 10).
This article focuses on the first two tasks.
|Table of Contents|
Before you start please note the following:
- Make sure to use the latest PowerShell version on your target systems;
- Make sure that the same PowerShell version is used on all of your target systems. If not, you may experience inconsistencies when executing your scripts on multiple systems;
- In this article, I assume that you are installing software on a 64-bit operating system.
Note: this article describes the creation of an SCCM package and NOT an SCCM application. SCCM applications are not used in a Citrix infrastructure. If you want to know why, please check the article Microsoft SCCM packages versus SCCM applications.
In summary, SCCM packages are preferred over SCCM applications because:
- Packages are easier to create and handle
- Packages are best suited for a state-less system
- Packages can be executed directly from an SCCM Distribution Point
This article will take you through the seven step process to create one single SCCM package. The process is the same independent of the contents of the package. A package can contain pretty much anything you like. A couple of examples:
- End-user applications (e.g. Adobe Reader, Microsoft Office)
- Server components (e.g. Visual C++ runtime, Java runtime, VDA, Receiver)
- Configurations (e.g. Windows roles and features, SCOM agent settings)
- System components (e.g. Citrix Delivery Controller, StoreFront)
For beginners, I recommend to go through the steps in order. Each step is described in detail.
Automating Citrix with SCCM starts with the "automation" part, the script. A script is not strictly necessary to execute a package, but I strongly recommend it. The script is the "trigger" of your software. It will trigger the installation, uninstallation, repair or configuration of your software.
I recommend to write this script in PowerShell. Please see the article PowerShell scripting template for SCCM packages for more information on how to create such as script.
The PowerShell script needs to be added to the source directory.
Most SCCM packages include source files. Source files are items such as installation files (e.g. MSI and setup.exe), configuration files (e.g. MyApp.xml, MyApp.ini, MyApp.reg) and the (PowerShell) script which manages the execution.
The source files of your package will be stored in a subdirectory of the SCCM package source. The package source is a central file share where the source files for all SCCM packages are stored. Your SCCM administrator can give you the exact UNC path (e.g. \\FileServer1\PackageSource).
|Maximum path length:|
On most operating systems the limit of the total path length is 255 characters. Please take this under consideration when designing your package source structure (https://msdn.microsoft.com/en-us/library/aa365247.aspx#maxpath).
When creating your package source please consider the structure carefully. The package source will grow substantially over time, so it is important to be able to find your packages easily. At the very least I would make one subfolder per vendor and add all software from this vendor to this directory. For example:
- \\FileServer1\PackageSource\Citrix\Delivery Controller
- \\FileServer1\PackageSource\Citrix\Citrix PVS Target Device
- \\FileServer1\PackageSource\Microsoft\VisualC 2015
- \\FileServer1\PackageSource\Microsoft\SCOM Agent
- \\FileServer1\PackageSource\Adobe\Acrobat Reader
Also, I recommend to create a subfolder for each version of the application as well as an internal versioning number ("_01"). For example:
- \\FileServer1\PackageSource\Citrix\Delivery Controller\22.214.171.124_01
- \\FileServer1\PackageSource\Citrix\Citrix PVS Target Device\126.96.36.19901_01
- \\FileServer1\PackageSource\Microsoft\VisualC 2015\14.0.23026.0_01
- \\FileServer1\PackageSource\Microsoft\SCOM Agent\7.1.10184.0_01
- \\FileServer1\PackageSource\Adobe\Acrobat Reader\11.0.18_01
This structure allows you to easily create a new package for a newer version of your application, but it also allows you to create a copy of an existing version, modify it, and release it without overwriting the existing package. For example:
- Multiple packages with the same application version:
- \\FileServer1\PackageSource\Adobe\Acrobat Reader\11.0.18_01
- \\FileServer1\PackageSource\Adobe\Acrobat Reader\11.0.18_02
- \\FileServer1\PackageSource\Adobe\Acrobat Reader\11.0.18_03
- Multiple packages with different application versions:
- \\FileServer1\PackageSource\Citrix\Citrix PVS Target Device\188.8.131.5219_01
- \\FileServer1\PackageSource\Citrix\Citrix PVS Target Device\184.108.40.20603_01
- \\FileServer1\PackageSource\Citrix\Citrix PVS Target Device\220.127.116.1101_01
In summary, these are the steps to complete:
- Create the package folder (e.g. \\FileServer1\PackageSource\Citrix\MyApp\Version)
- Create the appropriate subdirectories within the package folder. This will depend on the content of your package. For example:
- Copy your source files to the corresponding subdirectory
- Copy the main PowerShell script (and if you chose to use it, the CMD file) to the root directory: \\FileServer1\PackageSource\#Vendor#\MyApp\Version\AppInstaller.ps1
The next step is to create the SCCM package.
The SCCM package is the virtual container in SCCM containing all meta data regarding the installation, such as:
- Package name
- Package version
- Manufacturer (vendor)
- Command line
- Estimated disk space
- Maximum allowed runtime
- Package source directory (-> this is where your source files are stored)
- Programs (-> such as your installation, configure, repair and uninstall routines)
Creating the SCCM package involves a number of steps which are explained in detail below.
In the SCCM console go to the Software Library. Under Application Management \ Packages select the folder in which you want to create the package. With a right-mouse click, select Create package.
Enter the following information:
- Name: the name of the software (without including the manufacturer)
- Manufacturer: the name of the vendor of the software
- Language: the language of the software
- Version: the version number of the software
Select the tick box "This package contains source files" and add the correct parent folder of the source files (= your package source directory). The easiest way to add the directory is to copy it from a Windows Explorer window and paste it in the SCCM window. Click Next.
Now it is time to create the program, Select Standard program. Click Next.
|About SCCM programs:|
Each SCCM package contains at least one program. The program is a virtual object within the virtual application package (= the SCCM package). The program starts your PowerShell script (see the command line in the screenshot below).
One SCCM package may contain multiple programs. In most cases, a program represents the functionality of a script. For example, if you have an installation and an installation script within your package you will have to create two programs; one program which triggers the installation script and the second program which triggers the uninstallation script. You may also have a configuration or repair script. For these you also want to create additional programs.
The following screenshot shows our example SCCM package MyApp with four programs:
At the very least, one program is created for the installation part. Enter the following information
- Name: Install (can be any name you want)
- Command line:
- %WinDir%\Sysnative\WindowsPowershell\v1.0\powershell.exe -executionpolicy Bypass -file "AppInstaller.ps1" Install
- %WinDir%\Sysnative\WindowsPowershell\v1.0\powershell.exe -executionpolicy Bypass -file "AppInstaller.ps1" Uninstall
If using the ADT framework the command line is as follows:
- %WinDir%\Sysnative\WindowsPowershell\v1.0\powershell.exe -executionpolicy Bypass -file "Deploy-Application.ps1" Install
- %WinDir%\Sysnative\WindowsPowershell\v1.0\powershell.exe -executionpolicy Bypass -file "Deploy-Application.ps1" Uninstall
- Program can run: Whether or not a user is logged on
|AppInstaller.cmd and AppUninstaller.cmd:|
The command line examples above have one drawback: there is no error handling in case the PowerShell script itself ends in an error. This issue can be solved by creating a small batch file called AppInstaller.cmd containing the following lines:
%WinDir%\Sysnative\WindowsPowershell\v1.0\powershell.exe -executionpolicy Bypass -file "AppInstaller.ps1" Install >> C\Logs\AppInstaller.log
if %ERRORLEVEL% GTR 0 Exit %ErrorLevel%
You also need a batch file for the uninstall part (AppUninstaller.cmd):
%WinDir%\Sysnative\WindowsPowershell\v1.0\powershell.exe -executionpolicy Bypass -file "AppInstaller.ps1" Uninstall >> C\Logs\AppInstaller.log
if %ERRORLEVEL% GTR 0 Exit %ErrorLevel%
Copy this batch file in the root directory of your package source folder (this is the same directory as for the PowerShell script AppInstaller.ps1).
The command line of the SCCM package is: AppInstaller.cmd or AppUninstaller.cmd
|About the alias sysnative:|
The command line contains the special alias sysnative. This alias allows 32-bit applications to access the 64-bit native system directory. This alias launches a 64-bit powershell.exe.
The reason why this is needed is because the process smsswd.exe (C:\Windows\CCM), which is responsible for installing your SCCM packages, is a 32-bit process! Yes, even on a 64-bit operating system this process is still, as it was in SCCM 2007, 32-bit!
You want to start your script with the 64-bit version of the powershell.exe to be able to handle the installation of both 32-bit and 64-bit components. And this happens more often than not. Please remember that even when the application is 32-bit, any drivers or services included in the software will have to be 64-bit (on a 64-bit operating system of course).
The setting estimated disk space can be configured if you know how much hard disk space the software requires. If you do not have this information when creating the package, do not change the default value unknown.
The setting Maximum allowed run time is set to 120 minutes by default. If an application does not report back when the installation is finished or if a specific error occurs, the installation will hang for the full 120 minutes. It is therefore recommended to configure this value. For most installations, 15 minutes should be more than sufficient (this is also the minimum time allowed).
On the last page of the wizard check your settings and click Next.
Click Close to exit the wizard.
The package has now been created including one program called Install.
On each program within the SCCM package two settings need to be adjusted. Select the SCCM package and go to the Programs tab. With a right-mouse click on the program select Properties.
Select the tab OpsMgr Maintenance Mode and tick the box Disable Operations Manager alerts while this program runs.
If you want to create more programs, select the SCCM package and with a right-mouse select Create Program. Repeat the last two configurations for each package you create.
Note: the following configurations depend on the setup of your SCCM infrastructure. Concerning distribution settings it is best to discuss this topic with your SCCM administrator.
The SCCM package itself also needs to be configured. With a right-mouse click on the package select Properties.
On the tab Data Access tick the box Copy the content in this package [...].
On the tab Distribution Settings select Automatically download content when packages [...].
The SCCM package is now ready, but it still needs to be copied to the Distribution Points. SCCM does not install a package directly from the package source. Each SCCM server requires has a copy of the package in a special directory. With a right-mouse click on your package select Distribute Content.
In a larger SCCM infrastructure I recommend to work with distribution groups. A distribution group contains two or more SCCM servers. Citrix servers are normally placed in the data center. Your packages therefore do not need to be available on all distribution points in your environment. They only need to be copied to SCCM servers in the data center. Ask your SCCM administrator to create a special distribution point group for these SCCM servers. The main benefit is actually for the SCCM administrator, because it will save him or her a lot of disk space!
Go to Add \ Distribution Point Group.
In the window that appears select your distribution group and click OK. You now see that your distribution point group is listed. Click Next.
Your package is now ready to be used. Continue with the next step and create the task sequence.
After preparing the SCCM package it is time to create the task sequence. The task sequence we are creating will only contain one SCCM package (in some situations you may need to add more than one package). This task sequence will be a temporary one, used for testing purposes only.
The application task sequence will run on at least one server and it will allow the scripter to test the package deployment process. Applications on Citrix servers are always deployed using a task sequence, even when is only contains one single application.
In the SCCM console go to the Software Library. Under Operating Systems \ Task Sequences select the folder in which you want to create the task sequence. With a right-mouse click, select Create Task Sequence.
In the first step of the wizard select Create a new custom task sequence. Click Next.
Enter a name for your task sequence. Click Next.
The following step is to add your package(s) to the task sequence. With a right-mouse click on the task sequence select Edit. This opens the task sequence.
In the top menu click Add \ Software \ Install Package.
In the column on the left the new package appears. On the right side enter a name for the package. Use the Browse button to select the package you would like to add. In the Program section select the program. If you only have one program in your SCCM package this one is selected by default.
If you need to add more packages you can either copy a package within the task sequence or you can use the menu and select Add \ Software \ Install Package.
The next step is to create the collection.
Collections are basically groups in SCCM containing either users or machines. In a Citrix infrastructure software is always deployed on the machine. Before you can deploy your task sequence you first have to create the collection.
In the SCCM console go to the Assets and Compliance. Go to Device Collections. With a right-mouse click, select Create Device Collection.
In the first step in the wizard add a name for your collection and specify a limiting collection. This is new in SCCM 2012 compared to SCCM 2007. Click Next.
Add a membership rule. For testing purposes you can use a direct rule to add a machine to your collection. Make sure that the machine is also a member of the limiting collection you specified in the previous step!
If you do not add machines when creating the collection the following warning message appears. Click OK.
Click Close in the last step of the wizard.
Your collection is now created. The next step is to deploy the application task sequence.
Now it is time to deploy the task sequence to the collection.
In the SCCM console go to Software Library. Go to Operating Systems \ Task Sequences. Select your task sequence. With a right-mouse click, select Deploy.
Select the collection to which the task sequence should be deployed. Click Next.
Set the purpose to Available. This means that the deployment will be available in the SCCM Software Center (more about this in the following paragraph). Click Next.
Tick the boxes Software installation and System restart (if required to complete the installation). Click Next.
Select Access content directly from a distribution point […].
Note: if this option is not available, this means that you forgot to tick the box "Allow this program to be installed […]" on the program of the package (as described in the section Create the SCCM package). Click Next.
The task sequence has now been deployed successfully.
Continue with the next step testing the package.
After deploying the task sequence to the appropriate collection, the last step in the scripting process is to test the package on a target host.
During this test phase, the installation of the package is triggered manually. Therefore, the first step is to connect to the target server via RDP (mstsc.exe). This server has to be a member of the collection to which you just deployed your task sequence.
Open Control Panel \ Configuration Manager on the target host to which you just logged on. On the Actions tab select Machine Policy Retrieval & Evaluation Cycle and click the button Run Now.
Wait for a minute or so to give the SCCM client time to communicate with the SCCM server and to retrieve the list of available software.
After the update go to the Start Menu and launch the Software Center. This application is part of the SCCM client installation and enables you to install available software.
Under Available Software all new software packages are displayed. These packages either were never installed on this particular server or the package did not install successfully. Select the tick box in front of the task sequence you would like to install and either click the Install or Retry button.
The task sequence is initialized and you see the following window:
In case the installation ends in an error the following message is displayed:
There may be multiple reasons for an error. In no application specific log file was created in your log directory than the cause is most likely not the installation script itself. The error has something to do with the way the task sequence was launched. Perhaps the command line contains an error or you forgot to configure one if the settings mentioned in the paragraph Create the SCCM Package.
In this case, check the main SCCM error log on the server where you are testing. The log file is called smsts.log and is located in the directory: C:\Windows\CCM\Logs.
I personally like to use the tool cmtrace.exe to view the smsts.log file. You will see why when you open this file in Notepad. This tool is the Configuration Manager Trace Log Viewer for SCCM 2012. You can download it here: https://www.microsoft.com/en-us/download/details.aspx?id=50012. It is a good idea to add this tool to all target hosts in your environment.
In case you modified the contents of your source files please do not forget to update the distribution point. Go to Software Library \ Application Management \ Packages. Select your package and with right-mouse click select Update Distribution Points.
After you have fixed the error go back to the Configuration Manager and start the Machine Policy Retrieval & Evaluation Cycle. Than go to back the Software Center. You will find your task sequence in the tab Installation Status. The installation status is set to failed. Click the Retry button to start the installation once again.
This time your task sequence should run without problems and the status should be set to Installed.
And now you are done! Well, with your first package that is. Now you know one of the key elements in automating Citrix with SCCM; creating the SCCM package. You now need to go through these steps for each software component.
When you have created multiple packages you will have to add these to a major task sequence. This is the main task sequence containing all of your packages. This task sequence is used to install a server or to prepare a worker image completely unattended.