Back to top

Getting Started Guide: ConVirt for Hyper-V


1 Introduction

Welcome to ConVirt for Hyper-V. ConVirt is a multi-platform solution for managing your virtualization and cloud infrastructure, including VMware, Hyper-V, KVM, Xen, Amazon Web Services, OpenStack, and more. ConVirt enables you to manage thousands of hosts and virtual machines throughout their full lifecycle in a highly scalable and secure fashion, with advanced automation and orchestration features such as high availability, backup and recovery, policy-based workload management, and quota-managed self-service.

This document is a step-by-step guide for setting up a small "learning" environment to deploy ConVirt and try out its features. The steps are simple:

  1. Set up the ConVirt Management Server (CMS)
  2. Configure your Hyper-V hosts (no agent required!)
  3. Set up a Windows proxy server
  4. Open your browser and start managing your Hyper-V infrastructure

Note - this guide applies to ConVirt Enterprise 3.x and ConVirt Enterprise Cloud 3.x versions.

2 What You Will Need

The physical deployment architecture for ConVirt for Hyper-V shown in the diagram below is the minimum configuration needed to set up a "learning" environment.

Getting started hyperv.png

You'll need to ensure that the following pre-requisites are in place:

2.1 Host Servers

You will need 2 hosts in order to use ConVirt's advanced features. Each Hyper-V host should have the following minimum configuration:

  • Recommended Hardware
    • Dual-socket server
    • 64-bit processors that include hardware-assisted virtualization and hardware-enforced Data Execution Prevention (DEP)
    • 16 GB RAM
    • 200 GB free storage
  • NICs
    • Two 1-Gbps network interfaces - one for management and another for creating VMs on an isolated network
    • Using Hyper-V Manager, make sure that each physical NIC has a corresponding switch (see diagram below). In this guide we will use the following naming:
      • the External switch on the Management NIC is "hv-switch0"
      • the External switch on the VM NIC is "vm-switch0".
  • Supported Operating Systems
    • Fresh install of one of these
      • Windows Server 2012
      • Windows Server 2012 R2
    • Note - PowerShell remoting needs to be enabled on these hosts
  • Hypervisor
    • Hyper-V

Getting started hyperv4.png

2.2 Storage

  • Non-shared (local) storage
Note: ConVirt supports a broad set of shared storage options, but this requires a Hyper-V host cluster, which is beyond the scope of this guide.

2.3 Network

  • Internet access - you will need Internet access during your ConVirt setup, as some of the packages are downloaded over the network.
  • Domain access - make sure that both hosts are members of the same domain
  • Firewall - the firewall needs to allow a tcp connection on port 8080 for the proxy server

2.3.1 Self Service Option

In order to create self-service Virtual Data Centers, ConVirt transforms existing virtualized infrastructure into a cloud by overlaying an Infrastructure-as-a-Service (IaaS) layer. To manage this layer, you need to set up several network resources:

  • Network Service - one additional VM to be used as a network service (with Ubuntu 12.04 or CentOS 5.x/6.x). This VM will have connectivity to
    • Management Network : to configure/manage the Network Service
    • Private VLAN Network : for running virtual machines owned by different tenants/VDCs using VLAN
    • Public Network : to make virtual machines available on the public network.
  • VLAN ID pool - a set of free VLAN IDs.
  • Public IP pool - a few unused IP addresses on public networks to allocate to virtual machines

Instructions for setting up these Self Service Option resources can be found in the Set Up Network Resources section of the Feature Walkthrough: ConVirt for Hyper-V.

2.4 Client Machine/Browser

  • Browser - we recommend using Firefox as your browser for the ConVirt Management Server
  • Console - ConVirt uses an applet to invoke the vmconnect utility to connect from your client machine to a VM console. Pre-requisites are:
    • java installed on your client machine.
    • vmconnect utility (part of Hyper-V or RSAT tools for Hyper-V management) is present and is in PATH (other than windows/system32)
    • You must have Hyper-V Administrator privileges to view the console
    • Here are the steps to set this up:
      • cmd /c
      • dir /s vmconnect.exe
      • Pick c path that has WinSxS, and add it to PATH variable.
      • Select Computer from File Explorer, select properties and select "Advanced System Settings" link.
      • This will bring up a new dialog, select Environments button and in the system variables, select PATH variable. Press the Edit.. button.
      • Append the path for vmconnect.exe (the one containing WinSxS ) at the end. To do so, scroll to end, add a semi-colon (;) and the path.
      • Press ok/apply to save the changes.
      • To test this configuration, open a command windows or type "cmd /c" from powershell
      • echo %PATH% and make sure that the path you appended shows up.
      • Restart the browser(s)

3 Setting Up ConVirt

ConVirt manages Hyper-V hosts via a proxy machine. The ConVirt Management Server (CMS) talks to the proxy via http/https, and the proxy talks to the Hyper-V hosts using PowerShell.

Getting started hyperv3.png

Because we are setting up a simple "learning" environment, we will install the ConVirt Management System (CMS) and proxy as virtual machines on Host A, rather than on their own dedicated servers. The physical and virtual deployment architecture is shown in the diagram below:

Getting started hyperv2.png

3.1 Set Up ConVirt Management Server

Install the ConVirt Management Server (CMS) as a Linux virtual appliance running on Hyper-V Host A:

  1. Download the CMS appliance to Hyper-V Host A
    • Use the link you received in the Trial email from Convirture.
    • For Hyper-V, use the file version
  2. Deploy the CMS appliance on Hyper-V Host A and start it
    • Unzip the appliance to get to appliance disk file. (.vhd)
    • If you want to use the command line, open PowerShell as administrator on Host A and enter the following commands:
    New-VM -Name CMS -MemoryStartupBytes 4096MB -VHDPath <path_to_appliance_disk> -SwitchName hv-switch0
    Get-VM -Name CMS | Set-VM -ProcessorCount 2
    Get-VM -Name CMS | Start-VM
    • If you want to use Hyper-V Manager, use the following attributes:
      • Name = CMS
      • RAM = 4GB
      • Virtual CPU =2
      • Disk = use <path_to_appliance_disk>
      • Network = "hv-switch0"
  3. Start and connect to the CMS appliance VM console via Hyper-V Manager. You should see a Linux login - the credentials are:
    • user : cms
    • password : convirt
  4. Find the IP address of the appliance and note it for the next step:
    ifconfig eth0
  5. Open the CMS in your browser and activate the license
    • Start Firefox browser on another machine on the network
    • Using the IP address your discovered above, type in the url http://ip-address:8081
      • Troubleshooting - if the CMS does not come up in your browser, make sure that it is setup and running on the CMS appliance correctly:
        • Go into the CMS appliance and setup the CMS
          cd convirt-enterprise
          ./convirt-ctl setup
        • Start the CMS
          ./convirt-ctl start
        • Open the CMS in your browser at http://ip-address:8081
    • When the CMS opens, the License Management dialog will come up, so you can activate your trial license
    Licensemgmt licenseactivate.jpg
  6. Activate your Trial license
    • In the License Management-Activate License dialog, select the "Trial" radio button
    • Paste your Customer ID into the Customer ID text box
      • You received this ID in your ConVirt Trial Credentials email
    • Select "Activate" at the bottom of the dialog box
      • The CMS will connect to Convirture's license server
    • You should receive an alert "License applied successfully - Click OK to restart ConVirt". Click OK.
    Lic applied success.jpg
    • You should receive an alert "License activated successfully and ConVirt restarted - Click OK to login". Click OK.
    Lic activated success.jpg
    • You should see the Login panel for the CMS - login using the default credentials:
      • user : admin
      • password : admin

3.2 Set Up Managed Hosts

  1. Enable remote PowerShell access on each Hyper-V host
    • Start PowerShell as Administrator and executing the following commands:
    Enable-PSRemoting -force
    Enable-WSMANCredSSP -Role Server -Force

3.3 Set Up Hyper-V Proxy

We will set up the proxy as a Windows virtual machine running on Hyper-V Host A.

  1. Provision A Windows Server VM On Host A
    • Use Hyper-V Manager to provision the proxy VM with the following attributes:
      • OS= Windows (preferably the same version as the Hyper-V version being managed (e.g. Windows Server 2012 or Windows Server 2012 R2))
      • Name = hv_proxy
      • RAM = 4GB
      • Virtual CPU = 2
      • Disk = 100GB
      • Network = "hv-switch0"
    • Once you have created the VM, then Start it.
  2. Log in to the hv_proxy virtual machine as Administrator
  3. Install Hyper-V Client Tools
    • Open Server Manager (Start>Administrative Tools>Server Manager>Continue)
    • Under Features Summary, click Add Features.
    • On the Select Features page, expand Remote Server Administration Tools, and then expand Remote Administration Tools.
    • Click Hyper-V Tools, and then proceed through the rest of the wizard.
  4. Open PowerShell as Administrator
  5. Enable Access to Hyper-V Hosts
    • Test basic connectivity to Hyper-V hosts
    Get-VMHost -ComputerName <Hyper-V host name>
    • If the command is not successful, then make sure you have enabled remote PowerShell access as per the instructions in Section XX.
    • In addition, the CredSSP Client role must be enabled in the PowerShell window:
    Enable-WSMANCredSSP -Role Client -DelegateComputer <comma separated list of hyper-v computers> -Force
    • Additional Credential delegation
    Run c:\Windows\System32\gpedit.exe
    Traverse to Local Computer Policy--> Computer Configuration->Administrative Templates -> System -> Credentials Delegation
    Make sure that the following are enabled.
    Allow delegating fresh credentials
    Allow delegating fresh credentials with NTLM-Only Server Authetication
    For EACH of the options above,
    click to show details
    In "Options" section, Click the show button next to "Add servers to list".
    Add separate item for EACH hypervisor server with wsman/ prefix. For example: wsman/hv-01
  6. Setup Proxy Server
    • ConVirt uses PoSH server, an http server written in PowerShell, as the proxy engine.
    • Using an Administrator account, download and install PoSH server from Follow the instructions given here to start the PoshServer with the -HomeDirectory parameter.
    • Create a directory c:\hyperv-scripts to be accessed by Administrator only in the PowerShell window.
    • Use putty/pscp (download) or scp to transfer the the contents of src/convirt/core/platforms/hyperv-scripts/* from the CMS appliance into the new directory (in the PowerShell window).
    Invoke-WebRequest -OutFile c:\pscp.exe
    c:\pscp -r cms@<cms appliance IP>:/home/cms/convirt-enterprise/src/convirt/core/platforms/hyperv-scripts c:\
    • password: convirt
    • Set permissions that allow ConVirt scripts to be executed in the PowerShell window:
    Set-ExecutionPolicy Unrestricted
    gci c:\hyperv-scripts | unblock-file
    • Start the PoSHServer from the PowerShell window
    Start-PoSHServer -HomeDirectory "c:\hyperv-scripts"
    • Change the firewall to allow tcp connection on port 8080 (by default PoSH server listens on port 8080).
  7. Test the Hyper-V Proxy Setup
    • Open http://host:port/convirt_config.ps1.sample in your browser.
    • If the page is served correctly, then the proxy is working
    • If you get a 404 Error, then the proxy is not working, and you should check to make sure that you have started PoSH Server with the correct -HomeDirectory location.
  8. Advanced proxy setup
    • Because ConVirt sends credentials to the Hyper-V proxy node to get work done, it is strongly recommended that you use SSL and basic auth for production.
    • Get details on how to set this up here

3.4 Configure ConVirt To Use The Proxy

Go to the CMS virtual machine. Open the src/convirt/web/conivrt/development.ini and change the poshserver_url to point to Hyper-V proxy set up above.

e.g. poshserver_url = http://proxyserver:8080

Restart ConVirt

./convirt-ctl stop
./convirt-ctl start

4 The ConVirt Management Console

The ConVirt Management Console is a web-based dashboard that provides a single point of management and visibility into of your entire virtualized environment. ConVirt is multi-user, allowing the same environment to be managed by multiple administrators, and extensible, with multiple hooks for enterprise integration including LDAP/AD support, CLI, and API-based approaches.

Now that you have set up your hosts and installed the CMS and proxy, you are ready to log in to the ConVirt Management Console to start managing your virtualization environment. Open the ConVirt Management Console in your Firefox browser:


The default application credentials are :

user : admin
password : admin

The Console has 3 basic elements:

  A. Navigation Pane
  B. Detail Tabs
  C. Task Pane


4.1 Navigation Pane

This pane displays an organized, hierarchical view of each entity managed by the system, including Data Centers (Server Pools, Hosts, VMs, and Templates), Infrastructure-as-a-Service Clouds (IaaS), and Virtual Data Centers (Self Service). ConVirt has a highly interactive interface that allows you to use a context-sensitive menu on any entity to invoke the appropriate operations. For example, if you select a VM, you can right mouse click to get to the context menu and invoke the desired operations.

4.2 Detail Tabs

Each entity in the system has at least an Overview tab and a Configuration tab, and if appropriate, a Servers tab. The Overview tab shows summary information as well as information that requires attention. It also shows various charts that shows recent performance.

4.3 Task Pane

All operations within ConVirt are carried out via the task engine subsystem. It runs periodic tasks of monitoring hosts and virtual machines, data rollups and periodic maintenance. Information about the tasks submitted and their status is presented in the task pane at the bottom.

5 Adding Managed Hosts

When you first open ConVirt, you're faced with an empty Data Center. But with ConVirt's agentless architecture, bringing your virtualization hosts under management is a very simple discovery process. Just create a new server pool, then point to the hosts in your environment you want to add to the pool:

5.1 Create A Server Pool

  • Server pools allow you to manage a set of hosts in a uniform fashion, including shared storage, network resources, and automation policies.
  • In the Navigation pane, right click on the Data Center and select "Add Server Pool"
Add server pool.png
  • Select the virtualization platform, give your new server pool a name, then click OK.
Add server pool 2.png
  • You should get a confirmation, and the new server pool should show up in the Navigation pane under the Data Center.

5.2 Add Managed Hosts

  • Now that you've added a server pool, you can import your hosts
  • In the Navigation pane, right click on the server pool created above, and select "Add Server"
Add server pool 3.png
  • You will be prompted to select the platform. Choose the appropriate platform, then click OK.
Add server pool 4.png
  • Type the host name or IP address of the server, and a user name and password for an account with permission to access the server.
Add server pool 5.png
  • If the connection is successful, the managed Hyper-V host is added to the Convirt console. You can now create and manage the complete life cycle of virtual machines on this managed host.
Add server pool 6.png

6 Create And Manage Virtual Machines

ConVirt provides a toolset for day-to-day VM administration and lifecycle management, including templates-based provisioning, monitoring, configuration management, basic automation, live migration and much more.

6.1 Create A Template

A template is a set of related configuration information from which you can create one or more virtual machines. ConVirt ships with a set of default templates geared towards doing an ISO install, and can be easily customized to your environment.

First, lets create a template you can use with your Hyper-V environment. We're going to do this by cloning and modifying an existing template:

  1. Select the Template Library

  2. Drill down to the HyperV Templates group

  3. Right click on the template and select "Create Like":

  4. Enter a new name of the template and click OK.

  5. You should see the new template show up in the HyperV Templates group.

  6. Right click on the new template, and select Edit Settings.

  7. A Template Settings dialog box should pop up that will guide you through the process of editing the template. In the General section, change the default values to match your virtual machine template. For example, you can change the memory or change the number of virtual CPUs. In this example, we will create a Windows 8 virtual machine template.
    • For "Guest OS Flavor", select "Windows"
    • For "Guest OS Name", select "Windows 8"
    • For "Guest OS Version", select "SP2"

  8. Next we'll modify the template to use an ISO file to create new virtual machines, rather than the physical cdrom device.
    • Select Storage, and select the /cdrom storage disk. Note that the template uses some variables to identify the location and name of the ISO file to use:

    • Select Template Parameters and enter the ISO location and file name for your environment:

  9. Next you will identify the switch to use to connect the VM. Select the Networks tab, select the Default Network, and select Edit.

  10. Enter the name of the switch you want to connect the virtual machine to. e.g. VM-switch0, and click Save.


  11. Press OK. We just created a template that is suitable for provisioning multiple virtual machines in your environment.

6.2 Provision A Virtual Machine

Now that you have created your template, you can use it to provision a new virtual machine. There are several ways to provision a VM:

  • Provision on a server pool
  • Provision on a specific host
  • Provision from a template as the starting point

For this example, we will provision a VM on one of our host servers:

  1. Right click on the host, and select Provision Virtual Machine

  2. Select the virtual machine template you just created in the last section, and give the VM a name:
    • VM: hyperv-001 (or insert your own name here)

    • Click OK to provision the VM.
  3. You should see the new VM show up in the Navigation page under your Hyper-V host server.

6.3 Start & Connect To Your Virtual Machine

Now that you have provisioned your VM, you can start it, connect to it, and use it. And you can do all this from the ConVirt console:

  1. Right click on the new VM, and select Start.

  2. When the VM icon turns green, the VM has been started

  3. Right click on the VM, and select View Console

  4. ConVirt asks which viewer you want to use to view the console:

  5. Then ConVirt opens a console window to your new virtual machine.

Next: Feature Walkthrough: ConVirt for Hyper-V