VDI-in-a-box and Citrix Netscaler Access Gateway – Tying it all Together

We’ve recently been doing some work combining VDI-in-a-Box with Citrix Access Gateway in order to provide better performance to remote users than is possible by simply using RDP.  This article primarly deals with the integration of the 2 products, and assumes you already have a VDI-in-a-Box system configured provisioning virtual desktops for your users on demand.

The technology for this is Citrix Access Gateway.  In the past, this was available as a stand-alone virtual appliance however now this functionality is incorporated in the Citrix Netscaler product.  This is available as a VPX Virtual Appliance, and the lowest product in the range, Netscaler VPX Express, is free, but limited to a maximum throughput of 1mb per second – plenty for testing with a couple of users, but not much more than that.  For more details on Netscaler VPX, this PDF has a lot of useful info.  Citrix have an article on setting up VDI-in-a-box with NetScaler here, however it’s woefully inadequate – some of the included images are so low-resolution as to be incomprehensible (this one, for example – yes, that’s the full-resolution image direct from their support site!) and there’s no explanation of what you’re configuring or why which means if it doesn’t “just work” after following the steps, you’re pretty much on your own.

So here’s my attempt to produce some more useful instructions. First, a quick glossary and description of the components:

  • VDI Broker – This is the VDI-in-a-box “server” that manages provisioning and destroying virtual machines and allocating them to users.  Users log into a webpage with their usual credentials, and the VDI Broker either provisions a new virtual machine or assigns an existing machine to that user.  Once the VM is ready, the user is provided with an ICA file that gives Citrix Receiver the information it requires to connect to the new machine.
  • Citrix Receiver – This is client software that runs on the computer that the user is actually sat in front of and manages connections to Virtual Desktops using the ICA protocol.
  • Citrix Access Gateway (CAG) – This is a secure gateway between your Virtual Machines and the outside world.  Usually the Citrix Receiver would connect directly to the Virtual Machine’s IP address but it would not be secure or practical to allow access to all VMs from the internet.
  • NetScaler VPX – This is a fully-featured solution for publishing and securing all manner of web-based applications and services, however in this instance we’re only interested in it because it’s the cheapest and easiest way to get a Citrix Access Gateway.

And here’s a diagram of the network layout I’m using to test:


For my test environment I’m using 192.168.55.xxx to represent my “external” network, and 192.168.56.xxx to represent the “internal” network.  In this instance, as all of the machines and devices in question are virtual, this is a VMWare virtual network that lives only inside my ESXi box, but in a real deployment this would most likely be the existing network range used at the site hosting VDI-in-a-Box.

As you can see, even in the most basic test environment there’s still quite a bit going on.  It’s worth working out on advance where you’d like devices to live, and which IPs to use.

Netscaler will need an IP address to use to access its management console.  I’m using  This should be an “internal” address, as you’ll want to manage it from inside the network and not expose its management interface to the outside world.

VDI-in-a-box requires 2 IP addresses – one to use for management (I’m using, and one referred to as the “Grid” IP – this is the IP that desktops are provisioned through, and can be shared between multiple VDI-in-a-box servers in a multi-server configuration for reliability.  It’s also possible in more involved environments that this would be on a different network to the management IP.  I’m using for this.

The CAG will need 2 IPs.  It is acting as a “gateway”, so will need one “external” IP and one “internal”.  It will serve a login page on the external address, and use its internal address to access the internal network.  I’m using on the outside, and on the inside.

For most deployments you’ll also have a domain controller on the inside network.  Both CAG and VDI will connect to this using LDAP to authenticate clients.  In this instance I have a virtualised SBS2008 server on

It’s important to note that the CAG isn’t either a physical or virtual machine, it’s actually a service (helpfully called a “virtual server”, just to keep the terminology as confusing as possible) running on the Netscaler, in much the same way as Windows SMTP Server is a service that runs on Windows.

 Getting started:

Firstly we’ll need to collect all the software we’ll need.  I’ll assume VDI-in-a-box is already provisioned and running, as I intend to document this part of the process later, and it’s actually fairly well documented.  So we’ll need:

  • NetScaler VPX Express. Latest build at time of writing here – I can’t find a link to that file on Citrix’ site any more, they seem to be providing release 70.7 instead of 74.4, and in my experience that version doesn’t work properly.  74.4 has its own issues, but I’ll come to them in good time. You might need to create an account with Citrix to download that file – you’ll need one to generate a license later anyway. [Update: new version 75.7 available that fixes the license manager issue, here.]
  • Citrix Receiver.  You’ll need to install this on any client computer you want to connect to VDI-in-a-box from.  I used the version from here.
  • PuTTy and WinSCP – for remote console and file access to both the NetScaler and VDI-in-a-box.  I install these using ninite.

Extract the Netscaler VPX zip file, and you should find a VMDK virtual disk file, an mf file and an ovf file.  ESXi is happy to import from ovf, so file up the vSphere client, and select File > Deploy OVF Template.  The wizard will guide you through importing the virtual machine – settings to note are:

  • Disk provisioning, I tend to select “thin”, as the VPX is configured to use a 20GB disk but only requires around 400MB of this disk, so thick provisioning wastes a fair bit of space on the EXSi host
  • Virtual networks. Depending on your environment, you’ll probably want to map “VM Network” to your default ESXi network, with connectivity to the rest of your environment, and NS_NIC_1_1 to your ESXi virtual network.

Once you’ve run the wizard, it will upload your virtual disk to ESXi and create the VM.

Fire up the Netscaler virtual machine and open the console through vSphere, and you should be presented with the following:


Enter the details you’ll be using for the NetScaler’s internal address and then apply the settings.  NetScaler will then reboot, and start up using the IP you specified.  It should display this IP on the screen in the console, as below:


Open a web browser and make an https connection to the IP configured on the NetScaler, and log in using the default credentials – nsroot/nsroot.

Once you’ve logged in you’ll be presented with the NetScaler home page.  Initially we’ll want to run the Setup Wizard and configure some basic networking and authentication settings.

The first wizard page is Network Settings.  The management IP, subnet mask and gateway will already be populated with the settings you applied via the console.  You’ll need to set a host name (you way as well use the FQDN that you’ll be using for external connectivity – I’m using vdi.bluecompute.co.uk.  You’ll also need to set up either a MIP or a SNIP.  For simplicity we’ll use a MIP (Mapped IP) here – this is the IP address on the internal network that connections from the ouside world will be routed through when NetScaler is acting as a proxy or gateway.  As per the diagram above, in my test network this will be  If your virtual machines live on a different subnet to your management network, you’ll want to use a SNIP instead, but that’s beyond the scope of what we’re doing here.

We’re not using AppExpert, so you can skip the next page then click “Finish” to apply the IP settings and reboot the netscaler.  Once it’s rebooted, log in through a web browser again, and make a note of the “Host ID” (Actually the MAC Address) of the netscaler – you’ll need this to get a license from Citrix:


Log in to your “My Citrix” account, and go to the Netscaler VPX Express site here. Scroll right to the bottom of the page, expand the “License” section and click “Get License”.  Accept the license terms, and click the Serial Number of the license, this will take you to the “Allocate Licenses” page.  Enter the ”Host ID” collected earlier on the page and click continue, then download the license.

Back in the netscaler web interface, select “License” from the “System” menu, and click “Manage Licenses” – you can then upload your license file to enable the features we’ll require.

More detailed instructions for acquiring and applying licenses is available here.

Now we’re ready to actually set up the Citrix Access Gateway.

In the NetScaler web interface, select “Access Gateway” from the menu on the left, then select “Create/Monitor access gateway”.  This will start the Access Gateway wizard.  Click “Get Started, and you’ll be presented with the following screen:


Firstly we’ll need a name for the gateway (I call mine VDI-GW1), and an IP address.  This will be the external IP that users connect through – in my environment  This will be automatically be created as a “virtual IP” on the NetScaler.  You’ll also need to enter your internal mapped IP address, as discussed above, and select which port you’d like to serve the webpage on.  There’s also a checkbox to configure the gateway to also listen on port 80 for non-secure HTTP connections and redirect them to the secure login page.

Next is LDAP authentication. Here you’ll need to enter the details of your domain and domain controller:

  • IP Address: This is the address of your domain controller and should be on the “Internal” range.  Mine lives on
  • Port/Time out: Self-explanatory, I just left the defaults.
  • Base DN: This is the location in the directory that CAG should look in to see if the users exist, and have access – In the case of an SBS network you’ll need OU=SBSUsers,OU=Users,OU=MyBusiness,DC=Mydomain,DC=local – replace “Mydomain” with your Active Directory domain name, ie OU=SBSUsers,OU=Users,OU=MyBusiness,DC=BlueCompute,DC=local, but if only some of your users should have access this may be different.  You can set more advanced filtering, for example checking for membership of a particular security group, at a later point by modifying the LDAP policy.
  • Admin Base DN: This is the group that the server will check for memebership of in order to determine whether the user is an administrator.  The easiest option here is just use <admin_account_name>@<domain>.local – in my case networkadmin@bluecompute.local
  • Login name/password: This is the credentials that CAG will use to connect to the LDAP server – again you can just use a domain administrator account here, or set up a specific account for the purpose.

Scroll down to the next section of the wizard, which is “Certificate”. For testing you can just create a text certificate – enter a FQDN and descriptive file name. Note that if you do use a test certificate, you’ll need to install it on your client machines or the Citrix Receiver connection will silently fail.


Enter a DNS server for the netscaler to use, usually one of your DCs, and then tick the box to enable the “CloudGateway/Web Interface” – this is where the netscaler will act as a proxy for an internal web service, in this case VDI-In-A-Box.


Make sure both Single sign-on and ICA Proxy are checked – Single sign-on will reduce the number of times users need to enter their username and password before getting a desktop, and the ICA Proxy is required to allow multiple ICA Sessions from different IPs (the VDI Computers) to be accessed from a single address.

Click “Done” and the Netscaler will carry out the required steps to enable the Access Gateway.

The last thing we need to do is configure VDI-in-a-box to be aware that we’re using an Access Gateway so it can behave appropriately.  Log on to the VDI-in-a-box management interface (https://your-vdi-management-ip/admin) and log in. Select “Admin” > “Advanced Properties” and scroll down to the “Gateways” section.  We’ll need to enter 2 things here – the first is the ”External HDX Gateway Address”, which is the external address that your users will be connecting to.  This should be a fully-qualified domain name, and must match the name on the SSL Certificate that the Access Gateway is using, must not include a protocol prefix (such as https://) and must specify a port suffix (usually :443) .  The second is the “Internal HDX Gateway IP Address”.  This is the IP address that the Access Gateway will be connecting to VDI-In-A-Box from, or to put it another way, this is the “Mapped IP Address” that we configured earlier.  VDI-In-A-Box needs to know this because it must behave differently for proxied and direct connections.  It should look somewhat like this:


This is where the Citrix documentation leaves you.  I think it would be more helpful to at least explain what’s been configured and how to test it, and then in another post I’ll look at things that might not work, why that might be the case and how to make it so that it does, in fact, work.

At this stage it should be possible to log into the VDI-in-a-box Grid IP directly, be provisioned with a desktop and then be provided with an ICA file containing the information the Citrix Receiver needs to make an HDX connection to the desktop.  The ICA file (which is just text file and can be opened with any text editor) will contain an entry like this one:


This tells the Citrix Receiver which IP the newly-provisioned VM has acquired. On the local network, that IP address will be directly accessible, and you’re in business – no access gateway required.

It should also be possible at this stage to connect to the “External” address of your Access Gateway in a web browser.  This will initially present a Citrix VPN login screen


This takes domain credentials and creates an SSL tunnel through which connections to the VDI grid interface and the VM will be made.  Once authenticated here you should be presented with VDI-In-A-Box’s web login, but on the Access Gateway’s address as it’s being proxied according to the “Web Interface” settings on the access gateway:


Logging in here will again give you an ICA File, with a few important differences.  External to the local network (ie working remotely), the IP address of the provisioned VM won’t be accessible, so one of the things the Access Gateway does is re-write the ICA file to instead contain an entry giving the receiver the address of the proxy server, and changes the “Address” entry to contain the ID of a “Secure Ticket” that the Access Gateway uses to associate the connection with the correct VM:


These entries aren’t actually next to each other in the ICA file, the SSLProxy entry’s usually near the bottom, but as they’re the 2 entries we’re interested in I’ve put them together here.

Running this ICA file should allow the Citrix Receiver to connect to the Access Gateway specified in the “SSLProxyHost” entry and present the Secure Ticket to authenticate and identify itself.  The Access Gateway will then act as an ICA (or HDX) proxy, allowing the Citrix Receiver on the client to make a connection to the provisioned VM.  Assuming all your settings are correct, you’ll be presented with a beautiful, pristine desktop:


Now being realistic, this probably won’t happen.  There’s many many settings that I’ve glossed over that can prevent this from working so the next article will cover some of the things that can go wrong, how to get useful logging information and how to resolve these issues once they’re identified.


  1. bob

    Excellent article, thank you for taking the time to write it up. Can you offer any advice on adding in 2-factor authentication as well?

    • Admin

      Hi Bob,
      I haven’t yet set up dual-factor auth for our netscaler/VDI setup, and it’s currently on a client’s site being tested – I’m just having a look to see if I have the relevant VMs to do some 2-factor testing, if I do and get an article together I’ll post let you know.

      Cheers, Jim

  2. bob densley

    Excellent article, many thanks. When I hit the “Manage License” button in NetScaler, nothing happens! I’ve tried from 2 different PCs and different browsers. I’m using 74.4 (it’s the latest ver I believe). Any ideas?

    • Admin

      Hi Bob,

      My colleague that produced this post isn’t around at the moment, but I see he mentions a license manager issue in build 74.4, which apparently is fixed in build 75.7 onwards. I can see several later builds here: https://www.citrix.com/downloads/netscaler-adc/virtual-appliances/netscaler-vpx-release-10.html so I can only suggest trying one of those.


      • Bob Densley

        Thanks Alex, downloading now! Odd though because when originally downloaded Citrix pointed me to this version so I assumed it was the latest!
        Thank you for replying.

        • Admin

          No problem Bob, we exist only to serve.

  3. Admin

    Alex is right, it’s just an issue with build 74.4 which was resolved in later versions. And yes, that’s the one Citrix point people to – the QA process on their knowledge base articles is diabolical. Glad you got things working anyway Bob.

  4. Ken Sheppard

    Excellent article.

    We’re currently running ViaB 5.0.2 along with CAG Express 5.0.4. Our CAG free license is about to expire, so I need to replace with Netscaler VPX. However, in one of the steps you list, we have to use the ViaB Grid IP address but with 5.0.2, this option is not available in the advanced settings.

    We’re running a two server grid with XenServer and while we don’t have a Grid IP set, some type of Grid IP must be established internally as we only need to browse to one of the two ViaB servers to connect with HDX and all of our VMs are static/manual refresh VMs. When the users connect, ViaB 5.0.2 somehow knows which server is hosting their VM in the grid.

    Thanks for any input on how to get around this.

    • Admin

      Hi Ken,

      I don’t have a ViaB 5.0.2 setup to test on at the moment unfortunately, but the Citrix article here: http://support.citrix.com/article/CTX135013 offers a few alternative load-balancing options, although the only one that looks like it’d actually work in your environment is DNS round robin. It’s not a very tidy solution, and not recommended by Citrix – really you’re probably going to need to upgrade ViaB to 5.1 to make this work well I’m afraid.

  5. James

    Hi Ken,

    Would you know of a way to get thin clients working with such a setup without a browser based login, i.e. Wyse Thin OS Citrix reciever?

Leave a Comment