====== GRUB ======

This document will show you how to use the ''grub-x86_64 (xen)'' kernel to boot your servers. It contains instructions on how to migrate your current Xen system image from a hosted kernel to your system's own kernel and how to migrate your HVM server to Xen using GRUB.

Currently, ''grub-x86_64 (xen)'' is the default boot choice for all new servers using the official system images on Gandi Cloud Servers. It allows you to boot your systems using their own kernel, instead of hosted kernels maintained by Gandi, on our overhauled Xen infrastructure. Previously, the default was ''grub'' on our HVM platform, which we're moving away from.


===== 1 - Migrating an existing Xen server to GRUB =====

Follow these instructions to easily migrate an existing server from a hosted Xen kernel to GRUB. 

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 ''grub-x86_64 (xen)''.

<note warning>We recommend that you [[::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 server (or use ''sudo'') . For safety, follow the steps in the order they are presented.</note>

==== 1.1 - Migrate a Debian 7 Xen or Ubuntu 14.04 LTS Xen server ====

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

    local $> gandi vm ssh xenpv-server


Then, install or upgrade the ''gandi-hosting-vm2'' package, ''grub2'' and a kernel for your system:

    xenpv-server #> apt-get update

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

    xenpv-server #> apt-get install grub2-common

    xenpv-server #> apt-get install linux-image-amd64


Once all the packages are installed, update your GRUB configuration as follows to make sure that the following entry exists in `/etc/default/grub`:

    GRUB_CMDLINE_LINUX='console=hvc0 root=/dev/xvda1 nomce'


Then, run the following command to complete the configuration:

    xenpv-server #> update-grub2


At this point, you have installed all the necessary packages and made the required configurations to change your system's kernel. Move on to section 3 to continue the setup.

==== 1.2 - Migrate a CentOS 7 Xen server ====

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

    local $> gandi vm ssh xenpv-server


Then, install or upgrade the "gandi-hosting-vm2" package, grub2 and your system's default kernel:

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

    xenpv-server #> yum install kernel

    xenpv-server #> yum install grub2-efi grub2-tools


Once all the packages are installed, update or setup your GRUB configuration using the following instructions.

Make sure that the following entry exists in `/etc/default/grub` file:

    GRUB_CMDLINE_LINUX="console=hvc0 root=/dev/xvda1 nomce"


If the file doesn't exist on your system, create it with the following content:

    GRUB_DEFAULT=0

    GRUB_HIDDEN_TIMEOUT=0

    GRUB_HIDDEN_TIMEOUT_QUIET=true

    GRUB_TIMEOUT=0

    GRUB_DISTRIBUTOR=CentOS

    GRUB_CMDLINE_LINUX_DEFAULT="console=hvc0 nomce loglevel=5 net.ifnames=0 selinux=1 enforcing=0"

    GRUB_CMDLINE_LINUX=""

    GRUB_GFXPAYLOAD_LINUX=text

    GRUB_TERMINAL=console


Save the file and run this command to finish the configuration:

    xenpv-server #> grub2-mkconfig -o /boot/grub/grub.cfg


At this point, you have installed all the necessary packages and made the required configurations to change your system's kernel. Move on to section 3 to continue the setup.

====  1.3 - Migrating older / other distributions to GRUB ====

Older distributions might not have official support for ''grub2''. Depending on your OS family and version, you might need to install or build the necessary software using documentation provided elsewhere.

**We highly recommend that you opt for creating a new server using one of the officially supported systems. You can then migrate your data and applications to the new server instead of trying to migrate older distributions.**

If you still wish to migrate and older system to use GRUB, you should note that each distribution (or family) can have its own specific packages, paths and settings to boot with GRUB.

In general terms, it's important that you:

  * install the "gandi-hosting-vm2" package
  * install the "grub2" package
  * install a kernel for your distribution
  * have the following setting to your GRUB configuration to enable the emergency console: ''GRUB_CMDLINE_LINUX="console=hvc0 root=/dev/xvda1 nomce"''
  * update your grub config by running the appropriate command, such as ''update-grub2'' or ''grub2-mkconfig -o /boot/grub/grub.cfg'' -- note that every distribution might have its own tools.

Once these steps have been completed, you can change your server's boot option on the hosting platform itself as described in section 3.

===== 2 - Migrating an existing HVM server to Xen GRUB =====

Your server or system disk is set to run on the HVM platform if it uses one of the following kernels: “3.12-x86_64 (hvm)”, “3.18-x86_64 (hvm)”, “grub” or “raw”.

We have created a special script to help migrate HVM servers using official system images to Xen. Simply follow the steps below if you're operating a server on our HVM platform to install the necessary packages and perform the required system upgrades before moving on section 3 to complete your migration.

<note important>**Important**: if you have attached additional data disks to your server, please note that the device names will change from ''/dev/sdX'' (ex: ''/dev/sdb'') to ''/dev/xvdX'' (ex:
 ''/dev/xvdb''). Make sure that you make any necessary adaptations in your ''fstab'' or equivalent after running the migration script as explained below.</note>

=== 2.1 Migrating a Debian 7, Debian 8, Ubuntu 14.04 LTS or Ubuntu 16.04 LTS HVM server ===

To get started, access your current server as ''root'' with SSH (let's call it ''hvm-server'' in our examples):

    local $> gandi vm ssh xenpv-server --login root


Once you're connected, run the following commands. If you can't access your server as ''root'', prefix the commands with ''sudo'':

   hvm-server #> curl -s https://mirrors.gandi.net/gandi/pubkey | apt-key add -

    hvm-server #> apt-get update

    hvm-server #> apt-get install -y gandi-hosting-vm2

    hvm-server #> /usr/share/gandi/kvm_to_xen_migration.sh

    hvm-server #> exit


At this point, you have installed all the necessary packages and made the required configurations to change your system's kernel. Move on to section 3 to complete the setup.

=== 2.2 Migrating a CentOS 7 HVM server ===

To get started, access your current server as ''root'' with SSH (let's call it ''hvm-server'' in our examples):

    local $> gandi vm ssh xenpv-server --login root


Once you're connected, run the following commands. If you can't access your server as ''root'', prefix the commands with ''sudo'':

   hvm-server #> wget -O /etc/pki/rpm-gpg/RPM-GPG-KEY-Gandi https://mirrors.gandi.net/gandi/pubkey

    hvm-server #> yum install -y gandi-hosting-vm2

    hvm-server #> /usr/share/gandi/kvm_to_xen_migration.sh

    hvm-server #> exit


At this point, you have installed all the necessary packages and made the required configurations to change your system's kernel. Move on to section 3 to complete the setup.

=== 2.3 Migrating a HVM server running a custom image ===

Each distribution (or family) can have its own specific packages, paths and settings to boot with GRUB. In general, it's important that you:

  * install the "gandi-hosting-vm2" package
  * install the "grub2" package
  * install a kernel for your distribution
  * have the following setting to your GRUB configuration to enable the emergency console: ''GRUB_CMDLINE_LINUX="console=hvc0 root=/dev/xvda1 nomce"''
  * update your grub config by running the appropriate command, such as ''update-grub2'' or ''grub2-mkconfig -o /boot/grub/grub.cfg'' -- note that every distribution might have its own tools.

Once these steps have been completed, you can change your server's boot option on the hosting platform itself as described in section 3.

==== 3 - Setting the GRUB kernel on your server ====

==== 3.1 - Change your system's kernel ====

The following example uses Gandi CLI to change the kernel on your system disk. You can perform the same operation from your server's management interface on the website.

    local $> gandi disk update --kernel 'grub-x86_64 (xen)' --cmdline 'console=hvc0 root=/dev/xvda1 ro nosep' xenpv-server-disk 

    local $> gandi vm stop xenpv-server

    local $> gandi vm start xenpv-server


Now your system should use GRUB to boot the kernel you installed , instead of the hosted kernel it previously used.

==== 3.2 - Update your system's packages and kernel modules ====

Connect to your server again to update and upgrade any necessary packages, given the kernel upgrade.

    local $> gandi vm ssh xenpv-server


**On Ubuntu / Debian**:

    xenpv-server #> apt-get update

    xenpv-server #> apt-get upgrade

    xenpv-server #> reboot


**On CentOS / Fedora / Mandriva / Mageia**:

    xenpv-server #> yum update

    xenpv-server #> reboot


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

Finally, if you need to install specific kernel modules, you can refer to the instructions in this article: 

https://wiki.gandi.net/en/iaas/references/server/kernel_modules

And that should be enough to make your server run smoothly with GRUB!

===== 4 - Using a custom image with GRUB  =====

You can choose to run your servers with the [[::iaas:references:images|system images we provide and support]], or run them using your own kernels and systems with GRUB.

Take a look at our tutorial on how to use a custom image (packaged with VMDK in this example) to learn how to prepare, upload and use your own system images: https://wiki.gandi.net/en/iaas/tutorials/images/vmdk.

===== 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.