vSwitch and Controller

The vSwitch brings visibility, security, and control to Citrix Hypervisor virtualized network environments. It consists of the following components:

  • The vSwitch, a virtualization-aware switch running on each Citrix Hypervisor
  • The vSwitch Controller, a centralized server that manages and coordinates the behavior of each individual vSwitch to provide the appearance of a single vSwitch

The vSwitch Controller supports fine-grained security policies to control the flow of traffic sent to and from a VM. It provides a detailed view of the behavior and performance for all traffic in the virtual network environment. A vSwitch greatly simplifies IT administration within your environment. When using vSwitch, VM configuration and statistics stay bound to a VM even when it migrates from one physical host to another.


The vSwitch Controller is deprecated in Citrix Hypervisor 8.1 and will be removed in a future release.

Get started


  • At least one Citrix Hypervisor resource pool configured in XenCenter
  • Sufficient capacity within that pool to deploy the vSwitch Controller virtual appliance

The requirements for the host that runs the controller are described in the next section.


Setting up the vSwitch Controller involves the following tasks:

  1. Deploy the vSwitch Controller Virtual Appliance
  2. Access the vSwitch Controller
  3. Configure the vSwitch Controller IP address
  4. Add resource pools
  5. Configure high availability (optional)


This version of vSwitch Controller interoperates with all supported versions of Citrix Hypervisor.

Deploy the vSwitch Controller virtual appliance

The Citrix Hypervisor server that runs the vSwitch Controller must meet the following minimum requirements:

  • 2 CPUs
  • 2 GB DRAM
  • 16 GB Disk

The minimum allowed VM configuration for the vSwitch Controller appliance and the default configuration on import is:

  • 2 vCPUs
  • 2 GB DRAM
  • 16 GB Disk

This configuration supports pools of up to 16 Citrix Hypervisor servers and 256 Virtual Interfaces (VIFs) connected to the vSwitch Controller. For larger pools (up to the maximum supported limit of 64 Citrix Hypervisor servers in total for all pools and 1024 VIFs), modify the VM configuration to:

  • 4 vCPUs
  • 4 GB DRAM
  • 16 GB Disk


  • If the appliance’s disk is stored on a network storage, and is controlling the underlying Citrix Hypervisor host’s network traffic, deadlock can happen in loaded situations, and the entire pool’s network traffic can get stalled. To prevent this, Citrix strongly recommends customers to store the DVSC disk on a local storage or move the appliance into another pool which is not controlled by that DVSC.

  • For each pool, you must restrict the pool size to 16 hosts or less.

  • The vSwitch Controller is not supported in pools that use the Citrix Hypervisor PVS-Accelerator feature.

The vSwitch Controller VM can run within a resource pool that it manages. Generally, this configuration runs as if the vSwitch Controller VM was running separately. However, it might take slightly longer (up to two minutes) to connect all the vSwitches when a Controller migration or restart occurs. This time is because of differences in how the individual vSwitches route control connections.

To install the vSwitch Controller, import the supplied virtual appliance VM image into a Citrix Hypervisor resource pool. During import, attach the VIF of the imported VM to a network through which you can reach the host or pool that you want to control.

After the VM has been imported, start it to begin the process of configuring the DVS.

Access the vSwitch Controller command-line interface

You can access the vSwitch Controller command line interface (CLI) from within XenCenter or remotely using an SSH client. When the vSwitch Controller VM first boots, the console within XenCenter displays the IP address to use to access the controller remotely. If the VM did not receive an IP address, the text console indicates that an address must be assigned through the CLI. In either case, the text console displays a login prompt to log into the CLI locally in the XenCenter console. Full documentation of the available CLI commands is included in command line interface.

Access the vSwitch Controller GUI

Access the vSwitch Controller GUI remotely using a web browser or locally within the XenCenter console.


We recommend that the first time you log in to the vSwitch Controller you do so by using the GUI instead of the console. The vSwitch Controller GUI prompts you to change the password from the default value. Ensure that you set a strong administrator password to protect the security of environment.

When the vSwitch Controller VM boots, the console within XenCenter displays the IP address to use to access the GUI remotely. If the VM did not receive an IP address, the GUI cannot be used locally or remotely until one is assigned. The console provides instructions on setting the IP address locally in the command line interface. After the controller VM has the IP address, you can access the GUI locally within the XenCenter console.


If VNC is disabled, vSwitch Controller GUI can be accessed only from a web browser.

Access the vSwitch Controller GUI remotely

To access the vSwitch Controller interface remotely:

  1. Open a browser and type the following URL, where server is the IP address or host name of the interface of the controller VM: https://server-name:443/
  2. Type your user name and password, and click Login. The default administrator user name and password are admin and admin.
  3. If this is your first time logging in, the GUI prompts you to change the password from the default value. Ensure that you set a strong administrator password to protect the security of environment.


By default, the vSwitch Controller webserver uses a self-signed certificate. The certificate can cause browsers to show a security error when they connect to the GUI. You can safely ignore the error and install the certificate into your browser.

The following browsers are supported: Firefox 3.x, Safari 4.x, Internet Explorer 7 and 8. Other modern browsers with similar features (for example, Opera or Google Chrome) are not supported, but might work. Internet Explorer 9 addresses known memory and resource leak issues. However it has not received full testing.

Configure the vSwitch Controller IP address

When the vSwitch Controller is started for the first time, it attempts to obtain an IP address using DHCP. However, we recommend that you assign a static IP address. If DHCP is configured, resource pools cannot be set to Fail-Safe mode

To assign a static IP address:

  1. Access the vSwitch Controller interface locally.
  2. Select the Settings tab and then IP Configuration in the side panel. The current settings are shown.
  3. Select Modify Configuration, specify the new IP address information, and select Make Changes.
  4. Restart the vSwitch Controller Virtual Appliance.

Add resource pools

Adding a resource pool allows the vSwitch Controller to begin managing all Citrix Hypervisor servers in that pool automatically.

To add a resource pool:

  1. Under Visibility & Control, open the Status tab and choose All Resource Pools in the resource tree to open the Status page for all resource pools.
  2. Click Add Resource Pool. If you do not have the correct license to add another resource pool, an error message is displayed.
  3. Type the IP address or DNS name of the master Citrix Hypervisor server in the Pool Master Server (DNS/IP) box.
  4. Type the user name and password for administrative access to the server.

    The user must have full management capabilities in the resource pool. The vSwitch Controller cannot properly manage the pool when the account has restricted capabilities.

    Typically, this account is the user named root, but can be a different name when the RBAC features of the Citrix Hypervisor platform are in use.

  5. Choose the Steal check box only when you want to override any existing vSwitch Controller configuration for this resource pool.
  6. Click Connect.

The vSwitch Controller uses the provided user name and password to communicate with the pool master server using the XAPI protocol. When communications are established, the new resource pool is added to the resource tree, along with all of the associated resources. If the vSwitch Controller VM is unable to communicate with the pool master, it displays an error message describing the failure.


For the vSwitch Controller to communicate with the Citrix Hypervisor resource pool, the Citrix Hypervisor resource pool must use Backwards compatibility mode. This mode is the default. You can specify this setting on the Pool Properties page in XenCenter. For more information, see the XenCenter documentation.

Configure high availability

To ensure that Citrix Hypervisor servers can always reach an active vSwitch Controller, use Citrix Hypervisor high availability for the vSwitch Controller VM. For more information about enabling high availability on Citrix Hypervisor, see High Availability. Continuous operation of the vSwitch Controller is critical to the operation of networking for all VMs. To ensure high availability of the vSwitch Controller VM, set its restart-priority to 1 and ha-always-run to true.