Product Documentation

Citrix MCS for XenServer Connector

Jan 11, 2018

This article explains how to create a Platform layer that allows Layered Images to run flawlessly when deployed to Citrix MCS running on Citrix XenServer.  

Prerequisites: Platform layer for Citrix MCS

When creating a platform layer, the software installers for your platform must be available in a location that's accessible to the packaging machine (a virtual machine) where you are going to create the layer. 

Citrix MCS prerequisites

When you create a platform layer for publishing images to a Machine Creation Services environment, you need:

  • An OS layer

  • Network access to App Layering tools

    Access from the platform layer packaging machine virtual machine to the OS machine tools (in the installation download package).

  • Citrix Virtual Delivery Agent (VDA) installed on the platform layer

    Install the Citrix VDA installer for the Windows operating system you are using on the platform layer.

  • Citrix Delivery Controller

    Install the Citrix Delivery Controller software on the server where you publish the layered image.

    As part of the Connector Configuration, if you include a script to run on the newly published layered image, you need the following:

    • Agent - Installed and running on the Delivery Controller, which allows the appliance to run the script on the Delivery Controller.
    • PowerShell Snap-in - Install the appropriate PowerShell Snap-in on the Delivery Controller.
  • Citrix resource information

    The Citrix information listed in the topic Connectors for publishing.

Hypervisor prerequisites

You need any software and settings required to install your hypervisor onto the Platform layer. 

Connection Broker prerequisites

You need any installers, tools, and settings required to run your connection broker on the hypervisor you are using. 

Other tools and settings

  • App Layering OS Machine Tools download
  • KMS settings, if using KMS licensing

Prepare a new Platform layer

This section explains how to:

  • Prepare the layer by using the Create Platform Layer wizard
  • Deploy a packaging machine in your environment
  • Install the tools and configure the settings for Machine Creation Services
  • Finalize the layer

To create a platform layer, or add a new version to one

  1. Select Layers > Platform Layers and select Create Platform Layer in the Action bar. This opens the Create Platform Layer wizard.

  2. In the Version Details tab:
    1. (Required) Enter a name for the New Version. This can be the software version or other identifying information.
    2. For Base Version, select the version to use as the base for the new layer version. The default is the latest version. 
  3. On the OS Layer tab, select the OS layer that you want to associate with this platform layer.

  4. On the Connector tab, choose a Connector Configuration for the platform where you are creating this layer. If the configuration you need isn't listed, add a New Connector Configuration and select it from the list.

    Example: If you create the layer in your XenServer environment, select the XenServer connector with the information needed to access the temporary storage location where you package this layer.

  5. On the Platform Types tab, select This platform will be used for publishing Layered Images, and the hypervisor, Provisioning Service, and Connection Broker to which you will publish the layered image.

    Note: If you are not using any of the items in step 5, select None. For example, if you are not using a connection broker, 

  6. On the Packaging Disk tab, enter a file name for the Packaging Disk, and select the disk format. The disk is used for the Packaging Machine (the virtual machine) where you install the tools, as described in the next two sections.

  7. On the Icon Assignment tab, select an icon to assign to the layer. This icon represents the layer in the Layers Module.

    • To use an existing image, select an image in the image box.
    • To import a new image, click Browse and select an image in PNG or JPG format.
  8. On the Confirm and Complete tab, review the details of the app layer, enter a comment if required, and click Create Layer. Any comments you enter appear in the Information view Audit History.

  9. Expand the Tasks bar at the bottom of the page and double-click the packaging disk task to show the full task description.

    After creating the packaging disk, the Taskbar displays the location of the packaging disk in your environment.

Next, you can deploy the packaging machine for your layer.

Deploy a Packaging Machine

A packaging machine is a virtual machine where you install the tools for your selected environment.

Note: The packaging machine is a temporary virtual machine that is deleted when the new platform layer is finalized.

Log into the packaging machine

The Task Description (example shown in the last step above) contains the location of the packaging machine in your environment.

  1. Log on to XenCenter.
  2. In the management console, use the instructions in the expanded packaging disk task (shown below) to navigate to the packaging machine.

  3. Power on the packaging machine.

Install the platform tools on the Packaging Machine

This section explains how to install the platform software to be used by the platform layer. The platform software to install includes the provisioning server software and/or connection broker software that your layered images need to run in the target environment.

Keep in mind that the state of the software before you finalize the layer is what the image will use.

  1. Remote log on to the packaging machine you created. Be sure to log on by using the user account you used to create the operating system.

  2. Install the tools that your layered image needs to run in your environment. You can include any hypervisor, provisioning service, and connection broker software that you're using, along with any drivers, boot-level applications, and files needed.

    If a system restart is required during installation, restart it manually. The packaging machine does not restart automatically.

  3. Make sure the packaging machine is in the state you want it to be in when the image starts:

    • If the tools you install require any post-installation setup or registration, complete those steps now.
    • Remove any settings, configurations, files, mapped drives, or applications that you do not want to include on the packaging machine.

Next, you'll need to shut down the packaging machine and verify that the platform layer is ready to finalize.

Verify the Layer and shut down the Packaging Machine

Once the tools are installed on the Packaging Machine, the next step is to verify that the Layer is ready to finalize. At this point, any required post-installation processing needs to be completed. For example, a reboot may be required, or a Microsoft NGen process may need to complete.

To verify that any outstanding processes are complete, you can run the Shutdown For Finalize tool (icon below), which appears on the Packaging Machine's desktop.

To shut down the Packaging Machine so you can finalize the layer

  1. If you are not logged into the Packaging Machine, remote login as the user who created the machine.
  2. Double-click the Shutdown For Finalize icon. A command line window displays messages detailing the layer verification process.
  3. If there is an outstanding operation that must be completed before the Layer can be finalized, you are prompted to complete the process. For example, if a Microsoft NGen operation needs to complete, you may be able to expedite the NGen operation, as detailed below.
  4. Once any pending operations are complete, double-click the Shutdown For Finalize icon again. This shuts down the Packaging Machine.

The Layer is now ready to finalize.

Verify the Layer and shut down the Packaging Machine

Layer integrity messages you may see during the finalization process

Layer integrity messages let you know what queued tasks must be completed before a Layer is finalized.

The new Layer or Version can only be finalized when the following conditions have been addressed:

  • A reboot is pending to update drivers on the boot disk - please check and reboot the Packaging Machine.
  • A post-installation reboot is pending - please check and reboot the Packaging Machine.
  • An MSI install operation is in progress - please check the Packaging Machine.
  • A Microsoft NGen operation is in progress in the background.

Note: If a Microsoft NGen operation is in progress, you may be able to expedite it, as described in the next section.

Expediting a Microsoft NGen operation

NGen is the Microsoft Native Image Generator. It is part of the .NET system, and basically re-compiles .NET byte code into native images and constructs the registry entries to manage them. Windows will decide when to run NGen, based on what is being installed and what Windows detects in the configuration. When NGen is running, you must let it complete. An interrupted NGen operation can leave you with non-functioning .NET assemblies or other problems in the .NET system.

You have the choice of waiting for the NGen to complete in the background, or you can force the NGen to the foreground. You can also check the status of the NGen operation, as described below. However, every time you check the queue status, you are creating foreground activity, which might cause the background processing to temporarily pause.

Forcing the NGen to the foreground will allow you to view the progress and once the output has completed, you should be able to finalize the layer.

  1. Force an NGen operation to the foreground.

    Normally, NGen is a background operation and will pause if there is foreground activity. Bringing the task into the foreground can help the task to complete as quickly as possible. To do this:

    1. Open a command prompt as Administrator.

    2. Go to the Microsoft .NET Framework directory for the version currently in use:

      cd C:\Windows\Microsoft.NET\FrameworkNN\vX.X.XXXXX

    3. Enter the NGen command to execute the queued items:

      ngen update /force

      This brings the NGen task to the foreground in the command prompt, and lists the assemblies being compiled.

      Note: It’s okay if you see several "compilation failed" messages!

    4. Look in the Task Manager to see if an instance of MSCORSVW.EXE is running. If it is, you must allow it to complete, or re-run ngen update /force. Do not reboot to stop the task. You must allow it to complete.
  2. Check the status of an NGen operation

    1. Open a command prompt as Administrator.

    2. Check status by running this command:

      ngen queue status

    3. When you receive the following status, the NGen is complete, and you can finalize the Layer.

      "The .NET Runtime Optimization Service is stopped."

Finalize the Layer

Once the packaging machine is created, the software is installed and ready to finalize, and you have shut down the machine, you'll need to finalize the layer.

Note: When you finalize a layer, the App Layering software may delete the packaging machine so as not to incur extra cost for storage.

When the layer has been verified and is ready to finalize:

  1. Return to the management console.
  2. Select Layers > Platform Layers, and then the layer you just prepared.
  3. Select Finalize in the Action bar.
  4. Monitor the Taskbar to verify that the action completes successfully and that the layer is ready to deploy.