.. SPDX-License-Identifier: CC-BY-4.0 Getting started =============== Choose a base OS ---------------- You can install the Xen hypervisor in a number of base OSs, including numerous Linux distributions and some BSD flavours. Typical choices are AlpineLinux, Debian or FreeBSD; but you can use many others. .. note:: An easy rule of thumb is to check your base OS documentation on whether it supports running as a Xen :term:`dom0` (not to be confused with a Xen :term:`domU`). .. attention:: To support HVM guests, ensure that **virtualization extensions are enabled** in the BIOS. If your system does not support these extensions, you will be unable to use the hypervisor to virtualize unmodified OS systems. However, paravirtualization will work just well. The virtualization choices varies between BIOS releases, but are commonly referred to as "Enable Intel VT" for Intel chipsets, "Enable AMD-V" for AMD, or simply "Enable Virtualization Technology". Install the required packages ----------------------------- .. tab:: Debian **Reference link:** `Click here! `_ First, make sure your Debian system is up to date: .. code-block:: none sudo apt-get update && sudo apt-get upgrade Then, install the Xen project software: .. code-block:: none sudo apt-get install xen-system-amd64 .. tab:: AlpineLinux **Reference link:** `Click here! `_ First, activate the Alpine community repository (check `this `_ wiki page for more information), then install Xen and the seabios (BIOS) and ovmf (UEFI) firmwares for its virtual machines. .. code-block:: apk add xen xen-hypervisor seabios ovmf This will install Xen Hypervisor, the xl cli tool, and all necessary packages. The following step is to load the essential kernel modules for Xen. We will add them to :code:`/etc/modules`, so they will be loaded automatically at boot: .. code-block:: echo "xen-netback" >> /etc/modules echo "xen-blkback" >> /etc/modules echo "tun" >> /etc/modules Lastly, we set the default runlevel to include the Xen daemons. .. code-block:: rc-update add xenconsoled rc-update add xendomains rc-update add xenqemu rc-update add xenstored .. tab:: FreeBSD **Reference link:** `Click here! `_ **Xen Dom0 Package Installation** .. code-block:: pkg install -y xen-kernel xen-tools Configure your bootloader ------------------------- .. tab:: Debian After the installation process, Xen needs to be configured for it to boot. Open :code:`/etc/default/grub` (or :code:`/etc/default/grub.d/xen.cfg`) and look for a variable called :code:`GRUB_CMDLINE_XEN_DEFAULT`. If the variable isn't set, allocate enough memory and cpu's for it to run properly using the following syntax: .. code-block:: bash GRUB_CMDLINE_XEN_DEFAULT="dom0_mem=2G,max:2G dom0_max_vcpus=4" - **dom0_mem,max** sets the memory available to :term:`dom0` - **dom0_max_vcpus** to limit the number of vCPUs allocated for :term:`dom0` Then apply the changes and reboot as follows: .. code-block:: none sudo update-grub sudo reboot If the system doesn't boot properly (for example it freezes everytime), that might mean that not enough recources were allocated to the system. Try to play around with the values until the system works smoothly. .. tab:: AlpineLinux Once running a Xen kernel, you will have to change its command-line arguments and activate the default GRUB entry by writing this at the bottom of :code:`/etc/default/grub`: .. code-block:: bash # You need to set the amount of RAM to allocate to the Dom0 Alpine install so that # our future virtual machines will have enough memory. GRUB_CMDLINE_XEN_DEFAULT="dom0_mem=1024M,max:1024M" GRUB_DEFAULT="saved" GRUB_SAVEDEFAULT="true" Replace **1024M** with the amount of memory you want to dedicate to your :term:`dom0` operating system. After that, execute the following command: .. code-block:: grub-mkconfig -o /boot/grub/grub.cfg grub-set-default "$(grep ^menuentry /boot/grub/grub.cfg | grep Xen | cut -d \' -f 2 | head -1)" .. note:: This changes the default entry in GRUB to the first one containing 'Xen'. Run this each time you upgrade Alpine or Xen. .. tab:: FreeBSD After the installation was successful, follow the instructions given at the end of the packages which will say to modify :code:`/etc/sysctl.conf`, :code:`/etc/ttys` and :code:`/boot/loader.conf`. Also, Xen will require to add the following lines into :code:`/etc/rc.conf`: .. code-block:: bash cloned_interfaces="bridge0" ifconfig_bridge0="addm up" Finally, reboot the host to boot to the Xen kernel. .. note:: You should see the Xen kernel output and the FreeBSD kernel output. It is important to be aware of the **dom0_mem** and **dom0_max_vcpus** parameters in :code:`/boot/loader.conf`, especially on root-on-ZFS systems with ZFS ARC read caching. Post-install checks ------------------- Your next boot should start a Xen system. Verify this is the case by running :code:`xl info` on your terminal, which ought to print hypervisor details into your screen. .. warning:: :code:`xl` is a low-level CLI tool to communicate with the Xen hypervisor and requires you to run it with :code:`sudo` or as :code:`root`. Otherwise, the tool can't operate. .. attention:: If the xl command doesn't work by saying that no hypervisor was found, it means that the system hasn't booted with the hypervisor. If that's the case, double check you're selecting the appropriate menuentry when booting. A common mistake is having a :code:`GRUB_TIMEOUT=0` and the wrong :code:`GRUB_DEFAULT`. Check `this `_ page for more information on these options. Note that you can usually force the GRUB menu to appear (even when it's normally hidden) by holding SHIFT during early boot. Next steps ---------- You need to set up a suitable toolstack to create/list/destroy your :term:`domains`. If you're just playing around the easiest way to start creating them is through the :term:`xl` tool that you've installed as part of this section. See :doc:`guides/using_xl` to learn how to use it. Head over the :doc:`administration` page instead if you need a specialised administration setup.