Container management

Citrix Hypervisor supports the use of the following container types within your VMs:

  • Linux-based Docker containers hosted on Linux VMs
  • Windows Server Containers on a Windows Server 2016 VM

Citrix Hypervisor includes the following feature to enhance deployments of Docker containers on Citrix Hypervisor:

  • Container Management for Debian 8, and RHEL/CentOS/OEL 7

    When Container Management is enabled on a VM, Citrix Hypervisor becomes aware of any Docker containers running in the VM.

For more information, see What is Docker.

Citrix Hypervisor also includes the following feature to enhance deployments of Windows Server Containers on Citrix Hypervisor:

  • Preview of Container Management for Windows Server Containers on Windows Server 2016 Technology Preview

For more information, see What are Windows Server Containers.

Container Management Supplemental Pack


The Container Management Supplemental Pack is deprecated and will be removed in a future release.

The Container Management Supplemental Pack provides:

Monitoring and Visibility: allows you to see which VMs are in use for Docker hosting, and which containers on the VM are running.

Diagnostics: access is provided to basic container information such as forwarded network ports, and originating Docker image name. This feature can help accelerate investigations into problems where either the infrastructure and applications layers maybe impacted.

Performance: gives insight into which containers are running on that VM. Depending on the information provided by the operating system, it provides information on the processes and applications running on the container, and the CPU resource consumed.

Control Applications: enables you to use XenCenter to start, stop, and pause (if supported by the operating system) application containers enabling rapid termination of problematic applications.


Citrix Hypervisor supports installing Supplemental Packs using XenCenter. For information on how to install a supplemental pack using XenCenter, see the XenCenter documentation. If you would prefer to install using the xe CLI, see the Citrix Hypervisor Supplemental Packs and the DDK guide.

What is Docker?

Docker is an open platform for developers and system administrators to build, ship, and run distributed applications. A Docker container comprises just the application and its dependencies. It runs as an isolated process in user space on the host operating system, sharing the kernel and base filesystem with other containers. For more information, see


The Citrix Hypervisor Container Management feature complements, but not does replace the Docker environment. You can use one of the many Docker management tools available to manage individual Docker Engine instances in the VMs.

Manage containers on Linux VMs

To run Docker containers on your Linux VMs, first prepare your Linux VMs for Container Management. This feature is supported for Debian 8 and RHEL/CentOS/OEL 7 VMs only.

To prepare a Linux guest manually:

  1. Ensure that the VM has Citrix VM Tools for Linux installed, and that the VM network is configured as described in Network Requirements and Security.

  2. Install Docker, Ncat, and SSHD inside the VM.

    For RHEL/CentOS/OEL 7:

    yum install docker nmap openssh-server
  3. Enable autostart for docker.service:

    systemctl enable docker.service
  4. Start docker.service

    systemctl start docker.service

    Use a non-root user for container management. Add the user to the ‘docker’ group to provide access to Docker.

  5. Prepare the VM for container management; run the following command on the control domain (dom0) on one of the hosts in the pool:

    xscontainer-prepare-vm -v vm_uuid -u username

    Where vm_uuid is the VM to be prepared, and username is the user name on the VM that the Container Management uses for management access.

The preparation script guides you through the process and automatically enables container management for this VM.


If you migrate a Container Managed VM between pools, Container Management stops working for the VM. This behavior is because Container Management is implemented using a pool-specific key. To enable Container Management functionality again for the VM, run the xscontainer-prepare-vm command again on the VM. Even after running this command, the original Citrix Hypervisor pool might keep access to the VM.

Access the Docker Container console and logs

For Linux VMs, XenCenter enables customers to access the container console and view logs to manage and monitor applications running on Docker containers. To access the container console and logs using XenCenter:

  1. Select the container in the Resources pane.

  2. On the Container General Properties section, click View Console to view the container console. To see the console logs, click View Log. This action opens an SSH client on the machine running XenCenter.

  3. When prompted, log into the SSH client using the VM user name and password.


    Customers can automate the authentication process by configuring their public/private SSH keys. See the following section for details.

Automate the authentication process (optional)

When accessing the container console and logs, customers are required to enter the login credentials of the VM to authenticate SSH connections. However, customers can automate the authentication process to avoid entering the credentials manually. To configure the automatic authentication process, follow these instructions:

  1. Generate a public/private key pair.

  2. Add the public SSH key to the user directory on the VM running the container.

    For containers running on RHEL/CentOS/Oracle Linux 7 and Debian 8, manually add the public key to ~/.ssh/authorized_keys.

  3. Add the private SSH key to the %userprofile% directory on the machine running XenCenter and rename the key as ContainerManagement.ppk.

Authentication on Linux-based operating systems

Citrix Hypervisor’s Container Management uses a pool-specific 4096-bit private/public RSA-key-pair to authenticate on Container Managed VMs. The private key is stored in the Citrix Hypervisor Control Domain (dom0). The respective public-key is registered in Container Managed VMs during the preparation, either using the Cloud Config Drive or ~user/.ssh/authorized_keys file. As usual with all private/public key-pairs, the private key must be kept securely, as it allows for password-less access to all Container Managed VMs. This access includes both currently managed VMs and VMs managed in the past.

Citrix Hypervisor’s Container Management attempts to reach Container Managed VMs through any of the IP addresses advertised by the Citrix VM Tools running inside the VM. After an initial connection, Citrix Hypervisor stores the public key of container managed VMs and validates that the key matches on any subsequent connection. Ensure that only the Container Managed VM can be contacted through its advertised IP (using IP Source Guard or similar means). If the network topology cannot ensure this behavior, we recommend that administrators confirm the SSH hostkey that the Container Management obtained when making the first connection to the VM.

The key can be accessed by using the following command:

xe vm-parm-get-uuid=vm_uuid param-name=other-config  /

vm_uuid is the UUID of the VM


When using Citrix Hypervisor Container Management and Docker, be aware of the following behaviors:

  • Renaming a container does not trigger the Container Management view to update. This behavior can mean that Citrix Hypervisor might not show the current (renamed/paused/unpaused) container-status. The underlying cause is that the view only gets refreshed following Docker event notifications. As a workaround, the refresh can be triggered by performing an action (that is, start or stop) on an unrelated container on the same VM.

What are Windows Server Containers?

Windows Server Containers are part of the Windows Server 2016 guest operating system. They allow the encapsulation of Windows applications by isolating processes into their own namespace. Citrix Hypervisor Container Management supports monitoring and managing Windows Server Containers on Windows Server 2016 guest operating systems.

Manage Windows Server Containers


Windows Server 2016 VMs must be configured with one or more static IP addresses for TLS communication, as TLS server certificates are bound to certain IP addresses.

To prepare Windows Server Containers for Container Management:

  1. Ensure that the VM has Citrix VM Tools for Windows installed, and that the VM network is configured as described in Network Requirements and Security.

  2. Install Windows Server Container support inside the VM as described in Microsoft Documentation. Windows Server Containers are not Hyper-V Containers.

  3. Create a file called daemon.json in the folder C:\ProgramData\docker\config with the contents:

        "hosts": ["tcp://", "npipe://"],
        "tlsverify": true,
        "tlscacert": "C:\ProgramData\docker\certs.d\ca.pem",
        "tlscert": "C:\ProgramData\docker\certs.d\server-cert.pem",
        "tlskey": "C:\ProgramData\docker\certs.d\server-key.pem"
  4. Prepare the VM for container management; run one of the following commands on the control domain (dom0) on one of the hosts in the pool:

    Option 1 (for single-user VMs): Have Citrix Hypervisor generate TLS certificates for this VM.


    This option is only safe where only a single user has access to the VM. The TLS server and client keys are injected into the VM using a virtual CD. This information can be copied by malicious users during the preparation.

    xscontainer-prepare-vm -v vm_uuid -u root --mode tls --generate-certs

    Where vm_uuid is the VM to be prepared. Follow the on-screen instructions to complete the process of preparing Windows Server Containers. It involves interacting with dom0 and the VM.

    Option 2: To configure Citrix Hypervisor with externally generated TLS certificates

    xscontainer-prepare-vm -v vm_uuid -u root --mode tls \
        --client-cert client_cert --client-key client_key --ca-cert ca_cert

    Where vm_uuid is the VM to be prepared, client_cert is the TLS client certificate, client_key is the TLS client key, and ca_cert is the CA certificate.

Authentication for Windows Server Containers

Citrix Hypervisor uses TLS to monitor and control Windows Server Containers. In this instance Citrix Hypervisor acts as the TLS client, and Windows Server VMs act as the TLS server. Keys are stored in both Dom0 and the VM.


  • The client key must be kept securely, as it allows for password-less access to Docker on the VM
  • The server key must be kept securely, as it serves to authenticate the monitoring connection to the VM

When Citrix Hypervisor Container Management generates TLS certificates and keys by using the –generate-certs option, temporary CA, server, and client certificates are generated for a specific pool and VM. Certificates use sha256 hash and are valid for up to 2*365 days. After this time, repeat the preparation. The TLS connection is always established using a AES128-SHA cipher.

Network requirements and security


For container management to work, it might be necessary to relax security requirements regarding network isolation.

For maximum security of virtualization environments, we recommend that administrators partition the network by isolating Citrix Hypervisor’s management network (with Citrix Hypervisor Control Domain) from the VMs.

Enabling container management requires a route between these two networks, which increases the risk of malicious VMs attacking the management network (that is, dom0). To mitigate the risk of allowing traffic between the VM and the management network, we advise the configuration of firewall rules to allow only trusted sources to initiate a connection between the two networks.

Do not use this feature in production in the following cases:

  • If this recommended network configuration doesn’t match your risk profile
  • If you lack the necessary network or firewall expertise to secure this route sufficiently for your specific use-case

Network partitioning and firewalls

As with other VMs, do not connect container managed VMs directly to Citrix Hypervisor’s management network to provide the necessary isolation.

For Container Management to work, managed VMs have to be reachable from the Citrix Hypervisor’ s Control Domain (dom0). To monitor containers on Linux-based operating systems, the networking topology and firewalls must allow outbound SSH connections from dom0 to Container Managed VMs. To monitor Windows Server Containers, the networking topology and firewalls must allow outbound Docker TLS (destination TCP port 2376) connections from dom0 to Container Managed VMs.

To mitigate the risk of allowing traffic between the VM and the management network, pass all traffic through an external stateful firewall. This firewall must be manually set up and configured by an expert according to your specific business and security requirement.

The following section contains an example configuration:

To secure connections between the networks:

  • Prevent all connections between the Citrix Hypervisor management network (that is including dom0) and the VM network (that is including container managed VMs) either way.

Add exceptions for enabling Container Management:

  • To monitor a Linux-based operating system, allow dom0 to have outbound SSH (TCP port 22) connections (both NEW and ESTABLISHED) to Container Managed VMs.

  • To monitor Windows Server containers, allow dom0 to have outbound Docker TLS (TCP port 2376) connections (both NEW and ESTABLISHED) to Container Managed VMs.

  • Allow Container Managed VMs to reply to (ESTABLISHED) SSH and Docker TLS connections initiated by dom0.

Container management