.. _Ubuntu Service OS:

Using Ubuntu as the Service OS
##############################

This document builds on the :ref:`getting_started`, and explains how to use
Ubuntu instead of using `Clear Linux OS`_ as the Service OS with the ACRN
hypervisor. (Note that different OSes can be used for the Service and User OS.)
In the following instructions we'll build on material in the
:ref:`getting-started-apl-nuc`.

Install Ubuntu (natively)
*************************

Ubuntu 18.04.1 LTS was used throughout this document, other older versions such as
16.04 works too.

* Download Ubuntu 18.04 from the `Ubuntu 18.04.1 LTS (Bionic Beaver) page
  <http://releases.ubuntu.com/18.04.1/>`_ and select the `ubuntu-18.04.1-desktop-amd64.iso
  <http://releases.ubuntu.com/18.04.1/ubuntu-18.04.1-desktop-amd64.iso>`_ image.

* Follow Ubuntu's `online instructions <https://tutorials.ubuntu.com/tutorial/tutorial-install-ubuntu-desktop>`_
  to install it on your device.

.. note::
   Configure your device's proxy settings to have full internet access.

* While not strictly required, enabling SSH gives the user a very useful
  mechanism for accessing the Service OS remotely or when running one or more
  User OS (UOS). Follow these steps to enable it on the Ubuntu SOS:

  .. code-block:: none

     sudo apt-get install openssh-server
     sudo service ssh status
     sudo service ssh start

Install ACRN
************

ACRN components are distributed in source form, so you'll need to download
the source code, build it, and install it on your device.

1. Install the build tools and dependencies

   Follow the instructions found in the :ref:`getting-started-building` to
   install all the build tools and dependencies on your system.

#. Clone the `Project ACRN <https://github.com/projectacrn/acrn-hypervisor>`_
   code repository

   .. code-block:: none

      cd ~
      git clone https://github.com/projectacrn/acrn-hypervisor
      git checkout <known-good-tag/release>

   .. note::
      We clone the git repository above but it is also possible to download the
      tarball for any specific tag or release from the `Project ACRN Github
      release page <https://github.com/projectacrn/acrn-hypervisor/releases>`_

#. Build and install ACRN

   Here is the short version of how to build and install ACRN from source.

   .. code-block:: none

      cd ~/acrn-hypervisor
      make
      sudo make install

   For more details, please refer to the :ref:`getting-started-building`.

#. Install the hypervisor

   The ACRN devicemodel and tools were installed as part of the previous step.
   However, ``make install`` does not install the hypervisor (``acrn.efi``) on
   your EFI System Partition (ESP), nor does it configure your EFI firmware to
   boot it automatically. Follow the steps below to perform these operations
   and complete the ACRN installation.

   #. Add the ACRN hypervisor and Service OS kernel to it (as ``root``)

      .. code-block:: none

         ls /boot/efi/EFI/ubuntu/

      You should see the following output:

      .. code-block:: none

         fw  fwupx64.efi  grub.cfg  grubx64.efi  MokManager.efi  shimx64.efi

   #. Install the hypervisor (``acrn.efi``)

      .. code-block:: none

         sudo mkdir /boot/efi/EFI/acrn/
         sudo cp ~/acrn-hypervisor/build/hypervisor/acrn.efi /boot/efi/EFI/acrn/

   #. Configure the EFI firmware to boot the ACRN hypervisor by default

      .. code-block:: none

         # For SATA
         sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 \
                -L "ACRN Hypervisor" -u "bootloader=\EFI\ubuntu\grubx64.efi"
         # For NVMe
         sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/nvme0n1 -p 1 \
                -L "ACRN Hypervisor" -u "bootloader=\EFI\ubuntu\grubx64.efi"

   #. Verify that the "ACRN Hypervisor" is added and make sure it will be booted first

      .. code-block:: none

         sudo efibootmgr -v

   #. You can change the boot order at any time using ``efibootmgr -o XXX,XXX,XXX``

     .. code-block:: none

        sudo efibootmgr -o xxx,xxx,xxx

   .. note::
      By default, the "ACRN Hypervisor" you have just added should be
      the first one to boot. Verify this by using ``efibootmgr -v`` or
      by entering the EFI firmware at boot (using :kbd:`F10`)

Install the Service OS kernel
*****************************

You can download latest Service OS kernel from
`<https://download.clearlinux.org/releases/current/clear/x86_64/os/Packages/>`_

1. The latest Service OS kernel from the latest Clear Linux OS release
   from this area:
   https://download.clearlinux.org/releases/current/clear/x86_64/os/Packages.  Look for an
   ``.rpm`` file named ``linux-iot-lts2018-sos-<kernel-version>-<build-version>.x86_64.rpm``.

   While we recommend using the "current" (latest) release of Clear Linux OS, you can download
   a specific Clear Linux release from an area with that release number, e.g.:
   https://download.clearlinux.org/releases/26440/clear/x86_64/os/Packages/linux-iot-lts2018-sos-4.19.0-22.x86_64.rpm

#. Download and extract the latest Service OS kernel(this guide is based on 26440 as the current example)

   .. code-block:: none

      sudo mkdir ~/sos-kernel-build
      cd ~/sos-kernel-build
      wget https://download.clearlinux.org/releases/26440/clear/x86_64/os/Packages/linux-iot-lts2018-sos-4.19.0-22.x86_64.rpm
      sudo apt-get install rpm2cpio
      rpm2cpio linux-iot-lts2018-sos-4.19.0-22.x86_64.rpm | cpio -idmv

#. Install the SOS kernel and its drivers (modules)

   .. code-block:: none

      sudo cp -r ~/sos-kernel-build/usr/lib/modules/4.19.0-22.iot-lts2018-sos/ /lib/modules/
      sudo mkdir /boot/acrn/
      sudo cp ~/sos-kernel-build/usr/lib/kernel/org.clearlinux.iot-lts2018-sos.4.19.0-22  /boot/acrn/

#. Configure Grub to load the Service OS kernel

   * Modify the ``/etc/grub.d/40_custom`` file to create a new Grub entry that
     will boot the SOS kernel.

     .. code-block:: none

        menuentry 'ACRN ubuntu SOS' {
                recordfail
                load_video
                insmod gzio
                insmod part_gpt
                insmod ext2
                linux  /boot/acrn/org.clearlinux.iot-lts2018-sos.4.19.0-22  pci_devices_ignore=(0:18:1) console=tty0 console=ttyS0 root=PARTUUID=<UUID of rootfs partition> rw rootwait ignore_loglevel no_timer_check consoleblank=0 i915.nuclear_pageflip=1 i915.avail_planes_per_pipe=0x01010F i915.domain_plane_owners=0x011111110000 i915.enable_gvt=1 i915.enable_guc=0 hvlog=2M@0x1FE00000
        }

   .. note::
        You need to adjust this to use your partition UUID (``PARTUUID``) for
        the ``root=`` parameter (or use the device node directly).

   .. note::
        You will also need to adjust the kernel name if you used a different
        RPM file as the source of your Service OS kernel.

   .. note::
        The command line for the kernel in /etc/grub.d/40_custom should be all
        as a single line, not as multiple lines. Otherwise the kernel will fail to boot

   * Modify the ``/etc/default/grub`` file to make the grub menu visible when booting.
     There are a couple of lines to be modified, as shown below.

     .. code-block:: none

        #GRUB_TIMEOUT_STYLE=hidden
        #GRUB_HIDDEN_TIMEOUT=0
        GRUB_HIDDEN_TIMEOUT_QUIET=false

   * Update Grub on your system

     .. code-block:: none

        sudo update-grub

#. Reboot the system

   Reboot system. You should see the Grub menu with the new "ACRN ubuntu SOS"
   entry. Select it and proceed to booting the platform. The system will start
   the Ubuntu Desktop and you can now log in (as before).

   .. note::
       If you don't see the Grub menu after rebooting the system (and you're
       not booting into the ACRN hypervisor), you'll need to enter the
       EFI firmware at boot (using :kbd:`F10`) and manually select ``ACRN Hypervisor``.

   .. note::
       If you see a black screen on the first-time reboot after installing the ACRN Hypervisor,
       wait a few moments and the Ubuntu desktop will be displayed.

   To check if the hypervisor is effectively running, check ``dmesg``. The
   typical output of a successful installation will look like this:

   .. code-block:: none

      dmesg | grep ACRN
      [    0.000000] Hypervisor detected: ACRN
      [    0.862942] ACRN HVLog: acrn_hvlog_init

Prepare the User OS (UOS)
*************************

For the User OS, we are using the same `Clear Linux OS`_ release version as the Service OS.

* Download the Clear Linux OS image from `<https://download.clearlinux.org>`_

  .. code-block:: none

     cd ~
     wget https://download.clearlinux.org/releases/26440/clear/clear-26440-kvm.img.xz
     unxz clear-26440-kvm.img.xz

* Download the "kernel-iot-lts2018" kernel

  .. code-block:: none

     sudo mkdir ~/uos-kernel-build
     cd ~/uos-kernel-build
     wget https://download.clearlinux.org/releases/26440/clear/x86_64/os/Packages/linux-iot-lts2018-4.19.0-22.x86_64.rpm
     rpm2cpio linux-iot-lts2018-4.19.0-22.x86_64.rpm | cpio -idmv

* Update the UOS kernel modules

  .. code-block:: none

     sudo losetup -f -P --show ~/clear-26440-kvm.img
     sudo mount /dev/loop0p3 /mnt
     sudo cp -r ~/uos-kernel-build/usr/lib/modules/4.19.0-22.iot-lts2018/ /mnt/lib/modules/
     sudo cp -r ~/uos-kernel-build/usr/lib/kernel /lib/modules/
     sudo umount /mnt
     sync

  If you encounter a permission issue, follow these steps:

  .. code-block:: none

     sudo chmod 777 /dev/acrn_vhm

* One additional package is needed

  .. code-block:: none

     sudo apt-get install iasl
     sudo cp /usr/bin/iasl /usr/sbin/iasl

* Adjust ``launch_uos.sh``

  You need to adjust the ``/usr/share/acrn/samples/nuc/launch_uos.sh`` script
  to match your installation. These are the couple of lines you need to modify:

  .. code-block:: none

     -s 3,virtio-blk,~/clear-26440-kvm.img
     -k /lib/modules/kernel/default-iot-lts2018

  .. note::
      The image of UOS can be stored in other directories instead of ``~/``,
      and please remember to modify the directory of image in ``launch_uos.sh`` too.

Start the User OS (UOS)
***********************

You are now all set to start the User OS (UOS)

 .. code-block:: none

   sudo /usr/share/acrn/samples/nuc/launch_uos.sh

**Congratulations**, you are now watching the User OS booting up!


Enabling network sharing
************************

After booting up the SOS and UOS, network sharing must be enabled to give network
access to the UOS by enabling the TAP and networking bridge in the SOS.  The following
script example shows how to set this up (verified in Ubuntu 16.04 and 18.04 as the SOS).


 .. code-block:: none

    #!/bin/bash
    #setup bridge for uos network
    br=$(brctl show | grep acrn-br0)
    br=${br-:0:6}
    ip tuntap add dev tap0 mode tap

    # if bridge not existed
    if [ "$br"x != "acrn-br0"x ]; then
    #setup bridge for uos network
    brctl addbr acrn-br0
    brctl addif acrn-br0 enp3s0
    ifconfig enp3s0 0
    dhclient acrn-br0
    fi

    # Add TAP device to the bridge
    brctl addif acrn-br0 tap0
    ip link set dev tap0 up

.. note::
   The SOS network interface is called ``enp3s0`` in the script above. You will need
   to adjust the script if your system uses a different name (e.g. ``eno1``).

Enabling USB keyboard and mouse
*******************************

Please refer to :ref:`getting-started-apl-nuc` for enabling the
USB keyboard and mouse for the UOS.


.. _Clear Linux OS: https://clearlinux.org
