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

We recommend that you create a snapshot of your system disk before starting your migration.

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.

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.

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.

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 #> 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 #> 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 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:

  1. Detach your system disk from the VM ($ gandi disk detach my_boot_disk)
  2. Create a new temporary VM ($ gandi vm create –hostname temphvmfix)
  3. Attach your system disk to the temporary VM as a non-system disk ($ gandi disk attach my_boot_disk –vm temphvmfix)
  4. Fix the errors
  5. Detach the disk from the temporary VM ($ gandi disk detach my_boot_disk)
  6. Reattach the disk to your VM as its system disk ($ gandi disk attach my_boot_disk –vm my_original_vm)
  7. Resume testing

5.2 - Support

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

Last modified: 09/19/2017 at 16:56 by Alexandre L. (Gandi)