Project Curacao complete overview

VDI-in-a-Box, VIAB from now on, has been around for a few years and has not gone unnoticed. It’s still growing in popularity and new fans are added daily. Understandable, it’s easy to install and manage. Although it’s not for everyone, given the proper Business Case (and there are plenty) it just feels right. With this new release, which is still in Beta and not supported in production environments, some exiting new and improved features are introduced, like full Windows 8 / Server 2012 integration and the HDX protocol to name a few, perhaps making it an even more robust and likeable platform than it already was. Let’s first have a look on what it is about and highlight some of the main differences between VIAB and XenDesktop.


Simply put it’s an all in one solution, a single virtual appliance with the ability to create, provision, manage and load balance virtual desktops. It consists of a build-in connection broker, user manager, load balancer and desktop provisioning server. You don’t need shared storage, you can use it if you like but it’s not a necessity, no management servers or high speed connections and It runs on commodity hardware with your hypervisor of choice installed. This can either be XenServer, Hyper-V or VMware also no SCVMM, XenCenter or vCenter needed. Finally all this is managed from a single (vdiManager) web console.

Citrix also released the projectcuracaotechpreview.pdf document, you’ll have to log in with your My Citrix account to get it, have a look here: This is one of the documents I used to get my information. I’ll start off with some theory and then continue with the basic installation and configuration steps needed to get your infrastructure up and running. Finally I’ll address some general daily management tasks.

Global overview

Here’s a quote from Citrix: The VDI-in-a-Box appliance, known as VDI-in-a-Box Manager or vdiManager (more on this in a bit) runs as a virtual machine on a hypervisor. vdiManager creates and manages virtual desktops on the local physical server by communicating with the local hypervisor. A typical VDI-in-a-Box deployment might look like this:

VDI in a Box overview


This is basically what you download and install, it’s the hart of each VIAB infrastructure. It can be set up to run as a single physical server (or servers) or as part of a Grid which is a bunch of physical servers with the vdiManager bits installed grouped together. Each vdiManager part of a Grid can perform the following functions, see below. Of-course there’s a bit more to it when it comes to configuring these functions as we will see later on. I’ll try and tick all the boxes as far as installing and configuration goes.

  • Create virtual desktops from a template
  • Load balance across Grid
  • Provides high availability
  • Brokers connections
  • Provides a web based interface

Before we continue, let’s first have a look at some of the main differences between VIAB and XenDesktop, the more advanced VDI solution. If you think I forgot something please feel free to comment and I will add it to the list.

VIAB vs XenDesktop and vice versa

FlexCast… an advanced delivery technology part of XenDesktop capable of delivering all kinds of desktops and applications where VDI (the only one available in VIAB) is just one technology on its own. The FlexCast virtualization technology offers: Hosted Shared Desktops, Hosted VDI, Streamed VDI, Local VM and on demand Application delivery.

Authentication… Both VIAB and XenDesktop support Active Directory as well as smart cards. There’s one big difference, XenDesktop needs AD, VIAB also supports Workgroup environment, which might be just what you need in smaller environments. It has the option to create an internal database. A small plus for VIAB if you ask me.

Automation… XenDesktop offers an extensive PowerShell SDK interface that allow admins to automate various tasks like: desktop creation, site creation and a few more. VIAB is more basic, follow simple wizards to keep configuration and set up tasks to a minimum.

Policies… Although both products leverage the same HDX policy engine not all policies will apply to VIAB, next to that VIAB requires policies to be stored in AD where XenDesktop lets you store policies within the site database if that is what you need.

Scalability… VIAB has been proven to be quit robust (so I have been told :-) when it comes to larger environments, even up to thousands of desktops spread across multiple hypervisor hosts. Something to think about if VDI is your delivery model of choice.

Images… XenDesktop can make use of PVS and or MCS which adds to its flexibility but also complexibility, this also offers a way to work with different versions making it easier to identify and organize images. VIAB creates images by importing VM’s created outside the software. Next a wizard walks you through the process of installing the agent software, connection testing, image prepping etc… No versioning features here.

High Availability… Both XenDesktop and VIAB provide HA options, the both support shared storage and other redundancies. XenDesktop does have some additional HA requirements when it comes to its central database while VIAB uses local configuration files on each host.

And finally Costs… but that’s a no brainer!

The conclusion is as always, it all depends. You can make it as complex as you like, or perhaps, need to. And like I said earlier there are more differences out there. When it comes to selecting what best suites your wishes, you could be done with a snap of the finger so to speak or detailed research might be needed.


VIAB can use Active Directory authentication or plain simple Workgroups using a local user database. Active Directory is required in Windows domain environments and it can also be used to implement roaming profiles although I would recommend some kind of alternative third party profile management tool, Citrix profile management perhaps?! This will separate application configuration data and the My Documents folder from the desktop and thus providing a personalized desktop (sort of) each time a user logs on. In addition this will also greatly enhance the virtual desktop user experience.

User client access

Users can access VIAB desktops in three different ways, have a look below I copied these in from the projectcuracaotechpreview document:

  • Web browser. Web browsers support both HDX and RDP, although some configuration is required to use each protocol.
  • Citrix Receiver. Citrix Receiver allows direct access to VDI-in-a-Box desktops through an HDX connection without the use of a Web browser or Java client. Receiver connects to VDI-in-a-Box desktops on Windows, Mac, Linux, iOS, and Android platforms. With Citrix Receiver, older and low-end thin clients that do not have browsers can be used to access VDI-in-a-Box virtual desktops. Mobile devices, such as the iPad, can also be used with Receiver to access VDI-in-a-Box virtual desktops without requiring a Web browser or Java client.
  • VDI-in-a-Box Java Desktop Client The Java client automatically checks for updates and refreshes itself as needed. The client requires the Java Runtime Environment. The client switches to an RDP connection if an HDX connection is not available. Note that if you use the VDI-in-a-Box Java Desktop Client to access virtual desktops, you cannot use Access Gateway.

New and improved features

  • Windows 8 Personal Desktop support. Install applications etc…
  • Full Windows 8 support through HDX, not just RDP the way it just to be
  • Single Sign-On through Citrix Netscaler/Access Gateway on the VIAB web interface
  • SSL cert installation and Management UI. Wizard based SSL certificate installation
  • Error messages are now more specific toward end users using the VIAB web interface
  • Hypervisor address updates can be done through the server configuration settings
  • There’s now an improved image distribution troubleshooting tool
  • Full support for Windows Server 2012 VHDX format
  • Centralized log collections for multi-server Grids
  • The EULA is part of the set-up wizard

Server requirements

All major hypervisors are supported: XenServer 6.0.2 and 6.1 all editions, Microsoft Hyper-V Server 2012, Microsoft Hyper-V Server 2008 R2 SP1, Microsoft Windows Server 2008 R2 SP1 Enterprise Edition with the Hyper-V role enabled, Microsoft Windows Server 2008 R2 SP1 Core installation with the Hyper-V role enabled. VMware ESXi 5.1, VMware ESXi 5.0 Update 2, VMware Essentials license or greater is required. And I think they forgot one because I installed it on a Microsoft Windows Server 2012 installation with the Hyper-V role enabled and it worked just fine as far as I could tell.

Virtual Desktop requirements

Windows 8 Enterprise and Pro 32 and 64 bit versions, Windows 7 SP1 Professional and Enterprise 32 or 64 bit versions, Windows XP SP3 Professional edition 32 bit, Windows Server 2012 Full Standard edition 64 bit, Windows Server 2008 R2 SP1 Enterprise edition 64 bit, Windows 7 N is not supported. As per Citrix: Server sizing calculators are available. Citrix recommends that you use them when sizing servers for your VDI-in-a-Box deployment:

  • Partners: click VDI-in-a-Box, clickCitrix VDI-in-a-Box 5.2 Server Sizing Tool.
  • Customers: and click VDI-in-a-Box 5.2 Server Sizing Calculator.

Optional components

There are a bunch of optional components that integrate with VIAB and could enhance your VIAB experience, some new(er) than others. In most cases you’ll need at least one or two, have a look below. I won’t go into any detail:

  • HDX Optimization Pack for Google Earth. Improves the visual quality of images
  • Secure remote access. Access Gateway VPX 5.0.4. Access Gateway 10, RDS Gateway
  • VMware vCenter. Not required but integrates with VIAB if already used
  • Profile Management. Citrix Profile Management for example
  • Citrix HDX RealTime Optimization Pack for Microsoft Lync
  • Citrix Desktop Lock. Turn existing devices into thin clients
  • Citrix StoreFront. The Web Interface replacement
  • Application virtualization. Can you say XenApp?
  • And last but not least, Smart cards

Let’s get to it

If you would like to set up your own lab environment or just have a quick look go to: it’s the same link I started out with near the beginning. You will need to log in using your My Citrix credentials. Once logged in scroll down and select the appliance download referencing your hypervisor. I choose the Microsoft Hyper-V download since I still have my Hyper-V test lab up and running from the last time, It’s around 1.3 GB in total. Here you’ll also find the projectcuracaotechpreview document mentioned earlier and a bunch of optional components available for download as well.

Download and install

The download contains the VDI-in-a-Box Manager file which first needs to be unzipped to an .exe file of around 2 GB in size. Executing the .exe file will import the vdiManager into Hyper-V it does this by installing a VIAB Hyper-V connector in the background and the VIAB Manager appliance which will automatically appear as a virtual machine in your Hyper-V Manager. During the install wizard you have the option to install Hyper-V Remote Administration, I chose not to as we will see in a minute. The process is slightly different if you are using XenServer or VMware, the projectcuracaotechpreview document will tell you all you need to know. Let’s start by double clicking the .exe and go from there:

Intallation 1

Two components that get installed, first the Hyper-V connector which will run as a service once installed, it takes care of all communication between the hypervisor and VIAB Manager virtual appliance. Secondly the VDI-in-a-Box Manager virtual appliance itself, Click next.

Intallation 2

Unless you feel a need to change anything click next.

Intallation 3

The one I told you about earlier. I didn’t select it, don’t know why really. Just trying to keep it simple I guess. Selecting Enable Hyper-V Remote Administration enables you to manage the virtual desktops from a remote device, doesn’t sound like a bad idea come to think of it :-)

Intallation 4

There we go…

Intallation 5

Once the installation finishes, especially the Hyper-V connector bit took a while, this pops up, see above. If not already taken care of follow these steps for setting up and or installing your Hyper-V infrastructure. Next add the given IP address and look for the vdiManager appliance in your Hyper-V Manager, start it if needed and connect to its console to get the vdiManager web console URL. Since I already had everything up and running it worked like magic, the vdiManager appliance was just there!

Intallation 6

To finish it off. Below you see the vdiManager interface that appears if you connect to it from your Hyper-V Manager, it shows you the IP address needed to connect up to your vdiManager virtual appliance using your web browser. As a side note: When you are logged in to the VDI-in-a-Box virtual appliance (vdiManager) from your hypervisor console or by using an SSH client like PuTTY, you can change the appliance password which is recommended or obtain detailed logs for troubleshooting purposes. Check the Project Curacao documentation for login credentials.

vdiManager login

vdiManager virtual appliance

Open up your browser of choice and fill in the IP address. The Console Login page appears, see below. Here you will again need the projectcuracaotechpreview document to help you find the default username and password needed for login.

Console login

After the initial login you’ll first need to agree with Citrix, no harm in that right?

Console login 2

Hypervisor plus Grid

And there we have it, the connector set up, the virtual appliance imported and running and finally connected through a web interface ready for action. Let’s continue with the set-up of our Hypervisor infrastructure and VDI-in-a-Box Grid, although technically speaking not a Grid since I’m only using one vdiManager server, see below.

Console login 3

Click the Get Started button to get things moving and click Continue on the next page.

Console login 4

Fill in the IP address of your Hyper-V server and make sure you have an account with administrative privileges at hand, click next.

Console login 5

Next you need to decide where you store your images and virtual desktops that we will create later. Also, select the network to be used. I used Internal, this way my physical machine can communicate with my virtualized Domain Controller, but that’s just for lab purposes and testing only of-course.

Console login 6

That’s about it when it comes to setting up your hypervisor infrastructure. During the same wizard we continue with configuring our VIAB Grid. Naturally I choose to create a new VDI-in-a-Box Grid since it’s my first one.

Console login 7

Fill in the IP address of your Domain Controller, Domain name and administrative credentials or go with the VDI-in-a-Box Workgroup option, you decide. Hit next.

Console login 8

We’re almost done :-)

Console login 9

I selected No, here’s wat happend. Click Done and we are off to the next phase. It’s all good up till now right?

Console login 10

Base Desktop Image

This is where we need an existing virtual machine running in our hypervisor. After importing this VM it will be leveraged by VIAB to create a Base Desktop Image. This image, together with policies that we need to configure as part of the Template creation later on, will be used to provision our VIAB virtual machines at a later stage. This base image will either be copied when creating Pooled Desktops or in the case of Personal Desktop, where changes made to the VM are persistent, Linked Clones will be created. Click continue.

Console login 11

Next we need to select which existing and running VM we want to use.

Console login 12

So I did. In the mean time I fired up on of my Windows 8 VM’s.

Console login 13

After booting my Widows 8 VM I logged in locally and first turned off the firewall, next I enabled remote access through RDP. Both are necessary for this to function, at all. I refreshed and look what happened.

Console login 14

Althoug the Import button is already highlighted, you must fill in an description otherwise it won’t let you continue.

Console login 15

This took quit a while.

Console login 15

You can see it slowly progressing through all the steps necessary.

Console login 16

Won’t be long now…

Console login 17

Fortunately I did run into some errors :-) During my first try creating a base image it kept displaying the status Waiting for (remoting) protocol en then would finally time out displaying an error message stating that it timed out as Broken (status) while waiting for the RDP port 3389 to become available.

Console error

So my search started. I fist checked the projectcuracaotechpreview document, it has an section on creating your first image where it lists al conditions that your virtual machine must meet. I’ll list them here, check to see that:

  • The virtual machine is running one of the supported Windows operating systems
  • Enable File and Printer Sharing in firewall settings to allow remote agent installation
  • Ensure that your network is identified as a private or domain network.
  • Log on to the VM as the local administrator and enable remote connections
  • Remote Desktop Connection (RDP) functionality must be enabled
  • Enable the Local Administrator account on the virtual machine
  • Install your hypervisor’s management tools on the VM
  • The virtual machine has at least 4 GB of space available
  • The vVM must be started and in a powered on state
  • The VM has only one NIC and it is assigned Device 0
  • If desired join the virtual machine to a domain
  • The virtual machine has only one disk image
  • If using XP disable Use simple file sharing.

I used one of the Windows 8 running VM’s to create my first base image, but it kept failing. It goes without saying that I first checked all of the above, than I also tried to create an image by manually installing the Agent software, also unsuccessfully. Next Google led me to several CTX documents telling me that it could be firewall, group policy or DHCP related. I checked it all and all turned out fine. Then I had another look at my Windows 8 VM… Hey, it wasn’t activated since my test lab isn’t connected to the internet. Sure… I could pick up the phone but I didn’t :-) This was the only thing I could find that might interfere with me being able to successfully create my base image. I decided to go with one of my old XP Professional installation CD’s. So I fired up an extra VM, installed the OS followed by SP3 and walked through the above list. When I restarted the base image creation process I had my doubts but just a few minutes later…

Console login 19

Because I had chosen to manually install the agent software this still needed to be taken care of. I used the Copy to clipboard function and opened up an RDP connection to my newly created VM. Once logged in I opened up the web browser and pasted in the copied text followed by clicking the Install button.

Agent manual install

Monitor it’s progress…

Console login 20

And we’re done! No editing needed from my part.

Console login 21

Click view and tick the proper boxes.

Console login 22

Image prepping and provisioning, I’m sure we’re fine, click yes.

Console login 23

Lots going on, could take a few minutes.

Console login 24

Next we can do one more check, note that if you want to make any changes you’ll have to go back to the edit mode, which makes sence.

Console login 25

Choose how you would like to connect, we can now use HDX if we want!

Console login 26

One final step to take before we can start using our base image.

Console login 27

And there we have it, all done and in a Published state! Copying an existing base image does just that. A second copy will appear which will need to be edited once it turns up in a running state. Click edit and follow the instructions from the editing wizard. If you want to update an existing image you also use the edit option. A draft image will then be created. Again, when it shows up in a running state click edit and make the changes you want.  Next up are Templates.

Console login 28


Consist of an image, the one we just created, and policies. The image contains the operating system and applications, the bits and bytes. One image can be used by multiple templates. Policies are set as part of the template creation process they define things like, how many desktops to create, are they Pooled or Personal, how many desktops need to be Pre-started and more. It only takes a minute or two. On the main Template page click Add.

Template 1

It’s all pretty self-explanatory, give it a name, what would you like to connect during logon, memory, vCPU etc… Click View image details to get an overview on the image used for this particular template. Click next when finished.

Template 2

Again, how many desktops would you like to create from this template, do they need to be Pre-started? Etc… You can also make it the default template for creating new machines if you like. Notice that it isn’t possible to choose between either Pooled or Personal Desktops. Once you hit Save it’s a matter of seconds. For more information on the differences between Pooled and Personal Desktops review the projectcuracaotechpreview document or just give it a Google.

Assigning users

When done saving the template it will automatically continue (as it does after each phase we’ve gone through by the way) with assigning users to the template. On the general Users page we first need to configure our User Database, Workgroup or Active Directory. Click Configure to continue, you’ll end up with this.

Users 2

Fill in your domain name and credentials and click Save. Start adding users and or groups by choice, you will need to know the AD user or group names. When you click save it queries your AD and will either add-in the user or group or it will pop up with an AD search window with some possible alternatives already displayed.

Users 3

Now what?

That’s about it when it comes to setting up your base VDI-in-a-Box infrastructure. We do however need to have a look at some of the Servers and Admin pages available. Here we can adjust licensing, modify our hypervisor and or network settings, have a look at some advanced properties, Grid maintenance, Audit and debug logs etc… In the end there will still be some stuff left for you to figure out on your own, use the projectcuracaotechpreview document when needed. Especially the Manage chapter holds some valuable information when it comes to fine tuning your infrastructure, fun stuff!

The Desktops page doesn’t really show us anything special, the basics: how many desktops are in use, which template they are using, are there any broken, things like that. It also has a User Sessions tab showing us the connected users, their User-ID, Client name, Duration, status and more. Have a look at the Project Curacao documentation for more information on managing desktops in general, tasks like: refreshing Pooled and Personal Desktops, how to Log off, restart, shutdown, repair and destroy desktops, manage Personal Desktops etc. The same goes for managing User sessions as well, no rocket science but useful information none the less. The Recent Tasks and Events window below follows us wherever we go. We already covered the Images, Templates and Users tabs.

Servers tab

Click on the corresponding IP address of the server you would like to manage. The server properties window will open. Here we see some basic info on hardware used, OS and hypervisor versions, IP address of the vdiManager etc.

Servers tab 1

By selecting the hypervisor settings we can change the network used between our host and hypervisor, select another datastore or connect up to a whole separate hypervisor.

Servers tab 2

By clicking the VDI Manager network settings we can re-configure our vdiManager network settings if desired. We have three options, DHCP which is normally used if you have an address reserved, Static IP configuration speaks for itself and we can manually configure our network settings in case we have some exotic networking requirements.

Servers tab 3

Admin tab

I’ll start by giving you a general overview. First we the Advanced properties, it holds the syslog information, License server details, Grid failover settings, NTP server, external Manager addresses, internal and external HDX Gateway IP addresses including its FQDN, RDP Gateway address, several user session options and finally some miscellaneous settings used to fine tune your VIAB environment: max server load, max number of starting desktops at once, max number of starting Personal Desktop and a few more, definitely worth having a look!

Admin tab 1

Here’s an overview on some of the User session options available.

Admin tab 2

The Grid time is, well… the Grid time. Grid Maintenance puts the Grid in, or takes it out of Maintenance mode, needed for example when you would like to update your License with is right next to it on the screen. Manage Administrators, here you can add users who will then have access to the vdiManager console with the same access privileges as the vdiAdmin, I’m sure this will change (more options added) with time. The Audit and Debug logs are obvious and so is the Change Console Password option. Manage SSL Certificate gives you this, it’s now all wizard driven.

Admin tab 3

Last but not least, be very careful with the Reset Server option! Once confirmed it will delete all Templates and associated Users together with all the images in your datastore, meaning that you’ll have to start all over again.


With the exception of some minor errors it was a nice and smooth roll out. It only took me a few hours to set up and configure. I hope this post gives you an insight on what it takes to install and configure VDI-in-a-Box, Project Curacao in this case. Have fun and please give me some feedback on your experience with Curacao in the future. All comments are welcome!

Bas van Kaam ©

Reference materials used: Citrix E-Docs websit,e My Citrx and


9 thoughts on “Project Curacao complete overview”

  1. Pingback: URL
  2. Used the evaluation copy of VDI 5.2 and found no Citrix HDX connection. Is it only applicable to retail product?

    kind regards,

  3. Hi Rakesh,

    Thank you for your comment.

    I´m not sure, I didn´t use the 5.2 evaluation product. Perhaps the Administrator guide can provide you with an answer? The final (retail) product does support HDX, Windows Server 2012 included. Windows 8 is also supported but only through RDP.



  4. hi Bas, great review! For the Windows 8 image issues, if you could post it in the Project Curacao forum (link found on the Project Curacao download page), our developers will be happy to help track down the exact issue.

    Rakesh, VDI-in-a-Box 5.2 only comes with RDP connections to Windows 8 desktops (it of course gives you HDX connections to Windows 7 and Windows XP). So if you are talking about a Win8 image, what you saw is expected. HDX connections to Windows 8 only comes in Project Curacao and eventually the next VDI-in-a-Box release, version 5.3.


  5. Hello are you using WordPress for your site platform?
    I’m new to the blog world but I’m trying to get started and create
    my own. Do you require any html coding knowledge to
    make your own blog? Any help would be greatly appreciated!

    1. Hi, just go to or it will tell you all you need to know. But the short answer is no, you don’t need any HTML knowledge, at all! Let me know hoe it turns out.



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s