Getting Started with the Citrix App Layering Cloud API Service

Last week Citrix released a "Tech Preview" of the App Layering API.  The API as a starting point has some basic functionality that customers have been wanting for a long time such as querying layers and resources. The Citrix documentation provides a JSON spec but I also imported into Swagger to quickly see what it offers.  The API is very different than other Citrix SDKs\APIS in that it requires an on-premises appliance that communicates to the ELM appliance while the API calls are made over the internet.  This post will go over the basics of getting started and provide a script that provides some of the functionality.


Agent Appliance Configuration

In order to gain access to the appliance and API, you will need both a Citrix Cloud account ID and a submitted form requesting access.  Once the request is approved you will receive instructions on how to install the appliance and provide the needed Cloud account information.  Once the appliance is registered with Citrix cloud make note of the registration ID to be used later.


Registering ELM Appliance with Agent

Once the appliance is registered with Citrix Cloud the appliance then needs to register the on-prem ELM appliance.  In order to register the appliance you will need to identify your endpoint URL.  There are currently three.

Like all the Citrix Cloud APIs a token will need to be requested to do any further commands. In order to request a token your cloud id and secret will be used.  Again, the below code will be provided in a single script at the end of this post.

function Get-BearerToken {
param (
[string] $customerId,
[string] $clientId,
[string] $secret
$requestUri = "$customerId/tokens/clients"
$headers = @{"Content-Type"="application/json"}

$auth = @{
"ClientId" = $clientId
"ClientSecret" = $secret
$response = Invoke-RestMethod -Uri $requestUri -Method POST -Headers $headers -Body (ConvertTo-Json $auth)
return $response.token

This function will return a token to be used for all further commands. 

Now that we have our token we can register our ELM appliance with the API agent. In addition to the token you will also need the agent ID that we documented earlier, the IP or hostname of the ELM appliance and admin credentials.

function Invoke-ApplianceReg {
param (
[string] $customerId,
[string] $token,
[string] $url
$requestUri = $url + "/resources/"
$headers = @{
"Content-Type"="application/json; charset=utf-8"
"Authorization" = "CWSAuth bearer=$token"
"Accept" = "application/json;version=preview"
"Citrix-CustomerId" = $customerId
$body = @{
 "name"= "Butler's Appliance"
"description"= "A description of my App Layering appliance"
"type"= "Appliance"
"resourceLocationId"= "1333b292...."
"applianceConnection"= @{
"address"= ""
"auth"= @{
"credentials"= @{
"username" = "administrator"
"password" = "mypassword"
$response = Invoke-RestMethod -Uri $requestUri -Method POST -Headers $headers -Body ($body|ConvertTo-Json -Depth 5)
 return $response

Make sure to adjust the script to reflect your information.  Once the script is run you should receive information about your registration.


Sync Appliance

Once the ELM is registered it must be synced with the agent in order to receive the needed metadata such as layers and appliance info.

function Invoke-ApplianceSync {
param (
[Parameter(Mandatory = $true)]
[string] $customerId,
[Parameter(Mandatory = $true)]
[string] $token,
[Parameter(Mandatory = $true)]
[string] $url,
[Parameter(Mandatory = $true)]
[string] $ApplianceID

$headers = @{
"Content-Type" = "application/json; charset=utf-8"
"Authorization" = "CWSAuth bearer=$token"
"Accept" = "application/json;version=preview"
"Citrix-CustomerId" = $customerId
$requestUri = $url + "/resources/" + $ApplianceID + "/`$sync?async=true"
$response = Invoke-WebRequest -Uri $requestUri -Method POST -Headers $headers
return $response.headers.Location

This will return a Job URL that can be queried to see the progress.  After the job is completed you will notice further info available and you are ready to start automating!

Note: There is no automatic sync.  If layers are updated on the ELM a sync should be run to update the API agent


The Script

The script is available here that includes the above-mentioned functions and a few others to get you started.



Add a comment
  • Category: Citrix

Citrix Optimizer Community Template Marketplace

Recently, Martin Zugec from Citrix released version 2.0 of the popular Citrix Optimizer tool and one of the cool new features added is the ability to add custom template marketplaces.  Once added a marketplace can allow users to choose then download and upgrade specific templates all from the Optimizer GUI.  Out of the box, Optimizer includes a marketplace for all the Citrix maintained templates as you can see below.


After playing with the new version I thought it would be nice if there was a central location for the community to be able to submit, view and share their own custom templates.  I ended up creating a home for a marketplace on Github and this post goes over the introduction of the marketplace and how I hope the community can utilize it.

How to use the marketplace

Citrix Optimizer is designed to use XML for the marketplace data, including the URL location of a template and any metadata to display to the user such as author and version.  This makes it easy enough to simply point Optimizer to a custom XML URL and Optimizer will be able to render the information and allow templates to be downloaded or updated.  Let's go over the steps to add the community marketplace to Optimizer.

  1. From Citrix Optimizer select Template Marketplace from the left
  2. Select Add New Marketplace
  3. Add the URL and select Done
  4. Now on the left, you should see Citrix Community Marketplace
  5. Templates available to download will appear on the right
  6. As the marketplace grows this will allow users to download and update existing templates right from Optimizer

Submit Templates

This marketplace is worthless without templates.  If you have created custom templates I want them!  This section will go over how to submit your templates to the marketplace so they can be shared.


Template Format Rules

Before submitting there are a couple of rules that must be followed or else your submission\pull request will fail.

  1. Only templates created with Optimizer 2.0 will be allowed. (1.x will need to be converted)
  2. Only unique display names and ids will be allowed
  3. Template author name must match the directory name of the template


Submit via GIT

This is the preferred method.  If you haven't used GIT before this is a perfect situation to learn.  Don't get discouraged!

  1. First, you'll need a Github account
  2. Go to the Github repo at and fork to your own repo
    If you aren't familiar with this process I can't stress the benefits of at least learning the basics of GIT can be.  There are plenty of guides out there to help. Keep going!
  3. Within your fork go to the templates directory and create a new folder named the same as the author of the templates.
  4. Copy your template(s) to the newly created folder
  5. (Optional but highly recommended) Create a readme within your directory explaining your templates along with any other information you would like.  Feel free to include your contact info, twitter or whatever.
  6. An example of the layout can be found in the templates\Ryan Butler directory
  7. Once you're ready to submit to the marketplace you'll want to submit a pull request.
  8. If all the tests pass I'll be able to review and approve the PR making it part of the marketplace!

Note: There is no need to edit the communitymarketplace.xml file.  This will automatically be re-generated for each submission.


If you aren't comfortable with the GIT process feel free to reach out to me on Twitter or wherever else and I'll be happy to add them or help you get them submitted.

Add a comment

Automating App and OS Layers

Back in May I attended my local CUGC where Ron Oglesby presented a master class on Citrix App Layering (ELM) and after the presentation, it was asked if there was any sort an SDK. Ron explained that there is no public API or SDK (yet), but some of the newer ELM components were built with this in mind. This statement resonated with me and when I got home that afternoon, I fired up Fiddler to see how the API worked. After a rather lengthy process of reverse engineering the API with Fiddler, Postman and documenting the processes I was able to write my SDK. When I completed the SDK I wasn’t really sure how it could be utilized in an environment or if there would be a need. Figured it would be more useful around documenting an ELM environment vs actually automating the creation or updating layers. I was under the impression that if an organization could automate layer creation, chances are they could automate the entire image making ELM redundant. However, after thinking about it for some time I now see ELM in combination with automation potentially being the stopgap between manual installs\updates and a fully automated build. By automating certain aspects of ELM it could allow organizations to tiptoe into automation and create a comfort level and free up time otherwise spent on updating common layers. This allows administrators to continue manually installing the difficult applications or even controlled by other teams but allowing automation to keep the common apps (e.g. Firefox, Chrome, Notepad Plus Plus…) and OS layers fully updated on regular intervals.


The intent of this series of posts is how to approach automating some common apps and keeping the operating system layers fully updated.

  1. The first section will detail the steps needed for the script host and the base operating system layer allowing for automation.
  2. The second section will cover automatically building and updating app layers utilizing Choclatey packages.
  3. The third will cover continually keeping an operating system layer updated with Windows updates


Just some notes before getting started.

  • The SDK in these posts isn’t supported by Citrix so please TEST fully and make sure you understand what's taking place.
  • These guides are by no means the only way to approach automating ELM but a proof a concept to show it can be done and others can hopefully use as a base.
  • The process isn’t necessarily the most secure but again this is to show the possibilities so please run with care.
  • I really hope Citrix sees the value in having a supported SDK and the possibilities it can create to further the adoption of ELM.
Add a comment

Read more: Automating App and OS Layers

  • Category: Netscaler

Use Netscaler CPX for MAS Testing

After Synergy this year I watched a great presentation by Esther Barthel and Carsten Bruns (SYN220) where they covered MAS Stylebooks and Configuration Jobs.  After getting more and more comfortable with the playbooks they graciously provided, I wanted to create my own and needed a good test environment but didn't want to impact my VPX.  I could have deployed an additional VPX but figured CPX would be a good candidate since it can quickly be reset for testing.  While testing with Docker, I noticed each time my CPX container was shut down it was removed from MAS since it went unreachable.  I did some research and found that a CPX container could be registered with MAS saving a lot of time not having to re-register each time.  In this post, I'll cover how to use Docker with Docker-compose to deploy a CPX container and automatically register with MAS.



Add a comment

Read more: Use Netscaler CPX for MAS Testing

  • Category: Netscaler

Dynamically Load Balance Services with Netscaler CPX

This guide covers how a Netscaler CPX can be quickly deployed to automatically load balance web containers from a Docker-Compose file based on the number of web containers deployed.  The setup uses a PowerShell based script contained in a sidecar image that will add or remove servers from the Netscaler service group based upon the services registered in Consul. This guide is roughly based off of Chiradeep Vittal's demo found here.  For this guide I use Ubuntu 16.04 along with Docker 1.13 and Docker Compose 1.17.1.



Add a comment

Read more: Dynamically Load Balance Services with Netscaler...

  • Category: Netscaler

Running Pester Tests Against Citrix NetScaler

Pester is a testing framework that runs from Microsoft PowerShell allowing for quick test creation for a variety of usecases.  During a recent customer network upgrade I found Pester to be a great tool to validate Netscaler funtionality post-upgrade and thought I would create a simple healthcheck to share with the community.  In this post i'll cover getting started with a handful of simple Pester tests that you can use or modify for your environment.



Add a comment

Read more: Running Pester Tests Against Citrix NetScaler

  • Category: Citrix

Scripts Now Available on PSGallery

PowerShell Gallery

Github is an awesome resource to share and collaborate code but sometimes not the easiest if GIT isn't installed on a Windows Server.  Lately, I have been adding some of my more popular scripts to PSGALLERY which allows quick downloads and updates right from PowerShell.  In order to use PSgallery you will need to have PowerShell 5.0 installed or above and the first time you run the commands you will get prompted to install and configure the provider and modules.


To install the script simply run the install-script command and agree to the prompts.  For example to install the XDReplicate script run

install-script -name xdreplicate -Scope currentuser
NOTE: The currentuser scope installs under the current profile.  Otherwise the command will need to be run as administrator

To see what scripts are installed run



Now the cool thing is that you can simply update the script by running

update-script xdreplicate

To check what versions exist on the repository run

find-script xdreplicate

Or use tags

find-script -tag xendesktop

What scripts are available?

The following scripts have been added to PSGallery

 PSGallery Name Github Repo Description
 get-nslicexp  Grabs Netscaler license expiration information via REST.
 set-nsssl  A PowerShell script that enables TLS 1.2, disables SSLv2 and SSLv...
 PVSReplicate  Checks for vDisks and versioning and will export XML if required...
 XDReplicate  Exports XenDesktop site information such as administrators, deliv...
 get-ICAfile_v3  A Powershell v3 Script that utilizes invoke-webrequest to create,...
 get-ICAfile_v3_auth  A Powershell v3 Script that utilizes invoke-webrequest to create...


Add a comment
  • Category: Citrix

XenDesktop 7.x Site Replication Script

Sync You Very Much


If you have ever designed or implemented a mutli-site environment with Citrix XenDesktop 7.6 LTSR or greater chances are you deployed separate dedicated sites. Yes, there is the possibility of stretching the XenDesktop database across physical locations, utilizing connection leasing or even the newly introduced local host cache in 7.12. But, the problem with this architecture is it brings in strict latency and or environment size requirements that isn't always possible or cost effective.  Most of the time organizations end up with multiple XenDesktop sites and tasked with managing multiple sites totally independent from each other, which would include the separate management of user access, delivery groups, published applications and published desktops.  This can create major consistency issues from one site to the next and a huge headache with very dynamic environments for any Citrix admin.  To hopefully help with the problems encountered with this design I created a PowerShell script utilizing the Citrix XenDesktop PowerShell SDK that will export XenDesktop site data including published applications, desktops and a variety of other settings (see link below for full listing) from one site and import to another.  The script was designed so data will be exported from a main site and replicated to one or many secondary sites (think of robocopy for XD).  The script could easily be tied to a Windows Task Schedule or added to any workflow.


Please let me know of any comments or questions!

Add a comment
  • Category: Citrix

Reset XenMobile admin CLI password

This guide will go through the steps in resetting the local CLI admin account on a XenMobile 10.x virtual appliance.  Please be warned this is not approved by Citrix and i'm not responsible for any issues this causes!

What's needed

  • Linux bootable media (I used an Ubuntu desktop ISO)
  • Access to VM console of XenMobile appliance
  • You will need to reboot each node to complete
Add a comment

Read more: Reset XenMobile admin CLI password

  • Category: Octoblu

Send Citrix Director alerts to Slack via Octoblu

Getting Hooked

Citrix released XenDesktop 7.11 this week which brings a fantastic feature where alerts can be sent to webhooks.  Director now allows you to create alerts based on a variety of metrics and then send those alerts to a specific webhook when the threshold is met.  (Who needs email alerts??)  The main use documented by Citrix is for Octoblu, but I don't see why it wouldn't work for anything that has some REST capability like VMware Orchestrator, AWS Lambda, RES Automation...  This post will go over a simple alert based on CPU and then send that alert to a Slack channel with information on the alert.


What you'll need.

  • Octoblu account
  • Slack account and access to integrations
  • Access to Citrix director and DDC with XenDesktop 7.11 installed

  • Octoblu

  • Let's start with the basic configuration of the Octoblu workflow and grabbing the needed webhook URL used with director.  Lay out the workflow in a similar manner to the screenshot below.  I usually throw the debug switch on everything for troubleshooting.
  • title2
Add a comment

Read more: Send Citrix Director alerts to Slack via Octoblu

  • Category: Netscaler

Check Netscaler License Expiration Information Quickly via Powershell

All I did was reboot the thing!

If you have been dealing with Netscaler for awhile chances are you have rebooted an instance only to find no one can connect but everything is pingable.  After trying to refresh your browser multiple times, you frantically login to the Netscaler management IP and discover all your VIPs down, features disabled and SSL certificates no longer listed. WTF!

Add a comment

Read more: Check Netscaler License Expiration Information...