====== HVM at Gandi ======

<note important> As of June 2017, the HVM platform is deprecated. We're offering the same features on our Xen platform. Learn more in our official [[https://news.gandi.net/en/2017/07/a-more-xen-future/
|announcement]] </note>
===== 1 - What is HVM =====

Gandi's virtualization platform is migrating from [[http://wiki.xenproject.org/wiki/Paravirtualization_(PV)|XenPV]]  -- the open and powerful software virtualization technology that has been supporting our platform since 2008 --, to [[http://wiki.xen.org/wiki/Virtualization_Spectrum|PVHVM]] with [[http://www.linux-kvm.org/|KVM]] -- a mix of hardware and software virtualization that offers gains of performance and ease of use.

Now available for everyone for testing purposes, HVM-based servers offer the classic features of Gandi Servers 
-- such as [[https://www.gandi.net/hosting/iaas/livescaling|live-scaling of CPU*, RAM and disk]] --  and some new perks:
  * performance gains
  * ability to boot a hosted kernel (like on our current platform) or custom kernels using grub
  * compatible with any system that includes ''virtio'' and supports ''ACPI events''

//* Please note that hot-removal of CPU cores is not currently supported on the HVM platform. You need to stop the VM to remove CPU cores.//

You can now create HVM-based servers or start migrating current servers to the new platform. 

Choose between using the distributions with the kernel we provide, or build and install another system with a compatible custom kernel of your choice.

This document will show you how to get started. 

<note important>These instructions use [[http://cli.gandi.net|Gandi CLI]] to easily manage servers from the command line, but you can accomplish all the tasks via the web interface as well. </note>

===== 2 - Creating a new VM with HVM =====

We're providing three images containing an HVM-compatible 3.18 Linux kernel.

To create a new VM with HVM, simply run the following command (or select the image from the list if creating from the web interface):

**Debian 7**

    $ gandi vm create --image="Debian 7 64 bits (HVM)" --hostname <pick a hostname>

**Debian 8**

    $ gandi vm create --image="Debian 8 64 bits (HVM)" --hostname <pick a hostname>

**Ubuntu 14.04 LTS**

    $ gandi vm create --image="Ubuntu 14.04 64 bits LTS (HVM)" --hostname <pick a hostname>

Your fully-functional VM will be created and run on our HVM platform.

If you wish to use another distribution or a custom kernel, jump to the following sections.
===== 3 - Migrating an existing VM to HVM =====

Follow these instructions to easily migrate your existing server to the HVM platform. 

They'll walk you through the installation of the ''gandi-hosting-vm2'' package (which will also pull-in support ACPI event packages), tweaking some settings depending on your distribution and changing your kernel to ''3.18-x86_64 (hvm)''.

<note warning>We recommend that you [[http://wiki.gandi.net/en/iaas/references/disk/snapshots|create a snapshot]] of your system disk before starting your migration.</note>

<note important>You need to run the commands as **root** on your VM (or use ''sudo'') . For safety, follow the steps in the order they are presented.</note>

<note tip>If you're currently using a 32 bits system, we recommend instead that you migrate using GRUB (see below) or that you use a 64 bits distribution instead, if possible.</note>
==== 3.1 - Migrating a Debian 7 or Ubuntu 14.04 VM ====

=== 3.1.1 - Install dependencies ===

To get started, access your current VM (let's call it ''xenpv-server'' in our examples):

    local $> gandi vm ssh xenpv-server

Then, install the "gandi-hosting-vm2" package:

    xenpv-server #> apt-get install gandi-hosting-vm2

=== 3.1.2 - Edit system files ===

Copy-paste the following command to edit the ''/etc/fstab'' file:

    xenpv-server #> sed -i 's/xvda1/sda/' /etc/fstab

**Note for Ubuntu**    

On Ubuntu, you also need to change the ''/etc/mtab'' file. You can copy-paste and run this command to set the correct settings:

    xenpv-server #> sed -i 's/xvda1/sda/' /etc/mtab

**Note for Debian 7**

Copy-paste the following code to remove the gandi-config settings from ''/etc/inittab'' on Debian 7. The new settings will be inserted automatically by ''gandi-hosting-vm2'' at first boot.

    
    xenpv-server #> sed -i '/^# console configuration by gandi-config$/,$d' /etc/inittab
    

=== 3.1.3 - Update the system disk's kernel ===
Once you've done the manual edits on your Ubuntu or Debian machine,  you can upgrade your system's disk kernel to the HVM-compatible Linux 3.18 kernel we provide. Assuming your system disk is called ''xenpv-server-disk'', you can use:

    local $> gandi disk update xenpv-server-disk --kernel "3.18-x86_64 (hvm)" --cmdline 'root=/dev/sda'

=== 3.1.4 - Stop and restart ===
  
Now you can stop and start the VM and it'll be running on our HVM platform:

    local $> gandi vm stop xenpv-server  # soft rebooting won't hit the spot
    local $> gandi vm start xenpv-server

=== 3.1.5 - Update your system and reboot ===   

Finally, connect to your server again to update and upgrade any necessary packages, given the kernel upgrade:

    xenpv-server #> apt-get update
    xenpv-server #> apt-get upgrade
    xenpv-server #> reboot

And that should be enough to make your VM run smoothly on our HVM platform!

==== 3.2 - Migrating a CentOS, Fedora, Mageia or Mandriva VM ====

=== 3.2.1 - Install dependencies ===

To get started, access your current VM (let's call it ''xenpv-server'' in our examples):

    local $> gandi vm ssh xenpv-server

Then, install the "gandi-hosting-vm2" package:

    xenpv-server #> yum install gandi-hosting-vm2 

Or ''urpmi gandi-hosting-vm2'' on Mageia / Mandriva.

=== 3.2.2 - Edit system files ===

Copy-paste the following command to edit the ''/etc/fstab'' file:

    xenpv-server #> sed -i 's/xvda1/sda/' /etc/fstab

=== 3.2.3 - Update the system disk's kernel ===

Once you've done the manual edits on your machine,  you can upgrade your system's disk kernel to the HVM-compatible Linux 3.18 kernel we provide. Assuming your system disk is called ''xenpv-server-disk'', you can use:

    local $> gandi disk update xenpv-server-disk --kernel "3.18-x86_64 (hvm)"

=== 3.2.4 - Stop and restart ===
  
Now you can stop and start the VM and it'll be running on our HVM platform:

    local $> gandi vm stop xenpv-server  # soft rebooting won't hit the spot
    local $> gandi vm start xenpv-server

=== 3.2.5 - Update your system and reboot ===   

Finally, connect to your server again to update and upgrade any necessary packages, given the kernel upgrade:

    xenpv-server #> yum update
    xenpv-server #> reboot

With Mageia / Mandriva, you can use ''urpmi --auto-select'' if you're not using ''yum''.

And that should be enough to make your VM run smoothly on our HVM platform!
==== 3.3 - Migrating another distribution ====

You'll need to do some research to migrate other distributions to HVM while we work on providing more pre-built images. We recommend that you read the walk-through provided above and do your best to adapt the steps to your distribution. Basically, you'll need to:

  - Adapt and install the ''gandi-hosting-vm2'' package
  - Install the equivalent of the ''acpid'' and ''acpi-support-base'' packages that are available for your distribution (as they are dependencies of ''gandi-hosting-vm2'')
  - Change the ''/etc/fstab'', ''/etc/mtab'' and/or ''/etc/inittab'' files, or their equivalents, to use the settings specified above and/or in the package
  - Change the kernel of the VM's system disk to "3.18-x86_64 (hvm)", either using the CLI or the web interface
  - Stop and start the VM (not reboot or restart it)
  - Update and upgrade your system, and reboot for good luck

Look for troubleshooting tips and support contacts towards the bottom of this document if you encounter a roadblock.

===== 4 - Using a custom kernel  =====

On Gandi's HVM platform, you can choose to run your servers with the kernels and images we provide, or run them using your own kernels and systems either with GRUB or by booting directly from disk.

==== 4.1 - Boot custom kernels with our hosted GRUB =====

When launching a server with a grub kernel system disk, the host will boot the server using its own GRUB.
The host's GRUB  will then load your server's GRUB configuration from the default location on the attached system disk.

<note important>Your system's GRUB config file MUST be located at the following path: ''/boot/grub/grub.cfg''</note>

Your system disk, which can contain a custom kernel (i.e. a kernel or distribution not provided by Gandi), will then be used to boot your server, loading from the GRUB config and with the resources you allocated.

=== 4.1.1 - Migrating an existing server to the HVM platform with GRUB ===

You can follow the same instructions presented above to migrate a server with GRUB, but you'll need a different kernel and add additional configurations.

Once you have installed the necessary packages and edited the system files, choose the ''grub'' kernel (instead of the 3.18 (hvm) kernel). For example:

    local $> gandi disk update xenpv-server-disk --kernel grub
    local $> gandi vm stop xenpv-server
    local $> gandi vm start xenpv-server

=== 4.1.2 - Example with Debian and GRUB ===

In addition to the Debian-related instructions detailed above, and before changing your disk's kernel, follow these steps to boot your VM with GRUB on the HVM platform:

    hvm-server #> install -m 0755 -d -o root -g root /boot/grub
    hvm-server #> apt-get install grub2-common
    hvm-server #> apt-get install linux-image-amd64
    hvm-server #> grub-mkconfig -o /boot/grub/grub.cfg # or update-grub
    local $> gandi disk update hvm-server-disk --kernel grub 
    local $> gandi vm stop hvm-server
    local $> gandi vm start hvm-server
 
=== 4.1.3 - Migrating other distributions with GRUB ===

Each distribution (or family) can have its own specific packages, paths and settings to boot with GRUB. In general, it's important that you add the following setting to your GRUB configuration to enable the emergency console, in addition to placing your GRUB configuration at the path indicated above.

    GRUB_CMDLINE_LINUX='console=ttyS0'

==== 4.2 Running FreeBSD with GRUB (custom kernel example) ====

Place FreeBSD into a non-system disk that you attach to a temporary server, where you
include your GRUB config. Then create a brand new server and use the disk containing FreeBSD as the server's system disk.

First, you need to prepare your FreeBSD image locally. On a GNU/Linux workstation, for example:

  local $> qemu-img create -f raw freebsd.raw 3G
  local $> kvm -hda freebsd.raw -cdrom freebsd.iso -boot d -curses

''-curses'' option will facilitate copy/paste of following commands.

At the "Partitioning" screen, choose "Shell", then:
  # newfs /dev/ada0
  # cat << EOF > /tmp/bsdinstall_etc/fstab
  /dev/ada0 / ufs rw 1 1
  EOF
  # exit

At the "Network Configuration" screen, do not configure any network interface.

At the "Manual configuration" screen, open a shell, then:

  # mkdir /boot/grub
  # cat << EOF > /boot/grub/grub.cfg
  menuentry "FreeBSD" {
      insmod ufs2
      set root=(hd0)
      kfreebsd /boot/loader
  }
  EOF
  # sed -i -e s/ada/da/ /etc/fstab
  # echo ifconfig_vtnet0=dhcp >> /etc/rc.conf
  # exit

Then, you can add it to the server.

  local $> gandi vm create --hostname freebsd-temp-config

  local $> gandi disk create --name freebsd-system --vm freebsd-temp-config 

  local $> gandi vm ssh freebsd-temp-config

  freebsd-temp-config #> # copy your FreeBSD image to the server, then:
  freebsd-temp-config #> dd if=freebsd.raw of=/dev/<freebsd-system>

  local $> gandi vm create --hostname freebsd 
  local $> gandi disk update freebsd-system --kernel grub
  local $> gandi vm ssh freebsd 

  freebsd #> uname -a
  > FreeBSD freebsd X.X-RELEASE FreeBSD X.X-RELEASE [...)

<note tip>Known issues / Troubleshooting:

  - need to add the swap disk manually (swapon /dev/da1)
  - and to integrate ''gandi-hosting-vm2''
  - FreeBSD's default firewall, PF, has known performance issues in virtual environments. You can opt for IPFW instead, or deactivate TSO on network interfaces (''ifconfig_vtnet0="-tso DHCP"'')
</note>

==== 4.3 - Booting directly from disk  ====

You can make our host boot directly from your system disk if it provides its own MBR (master boot record), allowing you to use your own bootloader for example as if you were booting on a bare metal machine.

Whereas with GRUB you avoid the need to manage things such as MBRs, partitions and other lower level concerns, **you must tread with extra care when booting directly from disk**.

<note tip>By typing "exit" on a GRUB prompt you'll also boot from disk</note>

==== 4.4 Example with your own RAW image  ====

First, create a temporary VM with the HVM kernel and add :
  local $> gandi vm create --name temphvm --datacenter=LU --image="Debian 7 64 bits (HVM)"
  
Then, create and attach a new disk to this VM. This is the disk that you'll configure to be bootable.
  local $> gandi disk create --vm temphvm --name rawbootdisk
   
Use the temp VM to copy your boot image (using ''dd'' for example).

Once ready, detach the disk from the VM and change its kernel to ''raw'':

  local $> gandi disk detach rawbootdisk
  local $> gandi disk update rawbootdisk --kernel raw
  local $> gandi vm delete temphvm
  
Finally, create a new VM and use this disk as its system image:
  
  local $> gandi vm create --datacenter LU --image rawbootdisk

===== 5 -  Issues and Help =====

==== 5.1 - My VM won't boot anymore ====

If your VM is not booting after migrating to HVM , you can either revert the kernel back to 3.10 (or another non-HVM kernel) and start over, or detach the system disk and attach it to another VM for debugging:

  - Detach your system disk from the VM (''$ gandi disk detach my_boot_disk'')
  - Create a new temporary VM (''$ gandi vm create --hostname temphvmfix'')
  - Attach your system disk to the temporary VM as a non-system disk (''$ gandi disk attach my_boot_disk --vm temphvmfix'')
  - Fix the errors 
  - Detach the disk from the temporary VM (''$ gandi disk detach my_boot_disk'')
  - Reattach the disk to your VM as its system disk (''$ gandi disk attach my_boot_disk --vm my_original_vm'')
  - Resume testing
==== 5.2 -  Support ====

Please [[http://www.gandi.net/support/contact/|contact our Support team]] to report any issues.

You can also join #gandi on irc.freenode.net to hangout with our developers and other customers.