Product Documentation

Install the App Layering agent

The App Layering agent enables the App Layering appliance or a packaging machine in your hypervisor to run PowerShell commands locally. If you supply the proper credentials, the agent can run PowerShell commands as a specific user.

Note:

The App Layering agent is required if you want to do any of the following:

  • Publish layered images to PVS.
  • Use connector configurations. to launch a script.
  • Run App Layering in Microsoft Hyper-V.

If you are not using any of the above functionality, you do not need the agent.

The App Layering agent installer prompts you to register the agent with an App Layering appliance. If you do not register the agent during installation, you can manually register it later. However, remember that the PowerShell scripts do not run until the agent is registered with the appliance.

Prerequisites

Before you install the App Layering agent, make sure you that the system where you are installing the agent meets the following requirements:

  • An account with administrator privileges
  • .NET 4.5
  • PowerShell 3.0 or later
  • PowerShell Snap-in. Before using the App Layering agent on a Citrix Provisioning Services server, you must ensure that the PowerShell Snap-in is installed. See the steps below for manually registering the App Layering agent with the appliance.

If you previously installed the App Layering agent, you can download updated versions from the Citrix downloads page. The agent installation package is included in the App Layering ZIP download.

To download the App Layering agent

  1. Go to the Citrix home page and then click Sign in.
  2. Click Downloads and then select Citrix App Layering in the drop-down list.
  3. On the Citrix App Layering page, under Citrix App Layering > Product Software, click Citrix App Layering.
  4. At the bottom of the page, click Tools.
  5. Under Citrix App Layering agent, click Download File. The file citrix_app_layering_agent_installer.exe downloads to your computer.

Install the App Layering agent

The App Layering agent installer prompts you to register the agent with an App Layering appliance. If you do not register the agent during installation, you can manually register it later. However, keep in mind that the PowerShell scripts will not run until the agent is registered with the appliance.

  1. Using an account with administrator privileges, log into the system where you are installing the agent.

  2. Copy the Citrix_app_layering_agent_installer.exe file to a convenient location on the server.

  3. Run the Citrix_app_layering_agent_installer.exe as an administrator, and when prompted, enter the path to the directory where you want to install the App Layering agent. The default location is C:\Program Files (x86)\Citrix\Agent.

    The agent installer checks to see that all prerequisites are present. If any prerequisites are missing, the installer reports this and exits without installing.

  4. The installer prompts you for an Agent Port number. You can accept the default port number (8016) or specify a different one if the default port is already in use.

  5. The installer prompts you for the credentials (address, user name, and password) for your App Layering appliance. Register the App Layering agent with the appliance by entering the IP address and logon credentials for a management console user on the appliance with administrator privileges, (for example, the credentials you use to log on to the management console).

    Note:

    If the App Layering appliance is not available or you choose not to register with it now, you can manually register at a later time using the procedure described in Register with the App Layering appliance manually.

  6. Click Finish to exit the wizard.

Manually register the App Layering agent with the appliance

Register the App Layering agent with the appliance.

If the App Layering Agent is not registered with an App Layering appliance during installation, you can register it later by using the following procedure.

  1. As an administrator, log in to the server where you installed the App Layering agent.

  2. Open a command window (cmd.exe) as administrator and navigate to the directory where the App Layering Agent is installed. The default location is C:\Program Files (x86)\Citrix\Agent.

  3. Run the following PowerShell command:

    Enable-PSRemoting

  4. Verify that port 8016 is open by running this command:

    netstat -a

  5. Open a command window (cmd.exe) as administrator and navigate to the directory where the App Layering Agent is installed. The default location is:

    C:\Program Files (x86)\Citrix\Agent

  6. Run the following command, using the IP address of the appliance where indicated:

    Citrix.AppLayering.Agent.Service.exe register /i /e:IP_address_of_appliance /u:Administrator
    
  7. When prompted, enter the password for a user who has administrator privileges in the management console on the appliance.

  8. When the registration process finishes, a message appears informing you of the successful outcome. The App Layering agent registration appears in the audit log for the management service.

    If the process does not succeed, examine the C:\Program Files (x86)\Citrix\agent\Logs\applayering.agent.log file in the App Layering agent installation directory. You can also view Help for the App Layering agent command line options by running the following command:

    Citrix.AppLayering.Agent.Service.exe /?

  9. Run PowerShell command to load the appropriate dlls on the PVS Server.

    For PVS 7.7 and later:

    1. Navigate to:

      C:\program files\citrix\provisioning services console

    2. Run the command:

      C:\Windows\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe Citrix.PVS.snapin.dll

    For PVS 7.1–7.6:

    1. Navigate to:

      C:\program files\citrix\provisioning services console

    2. Run the command:

      C:\Windows\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe McliPSSnapIn.dll

    Under some circumstances, all of the PVS and Broker snap-ins may be unregistered. For instance, this can happen on a major Windows update. To find out whether all snap-ins are registered:

  10. Run the following command to list the registered snap-ins:

    get-pssnapin -registered

  11. See this article for instructions to reregister all snap-ins.