Using Ubuntu as the Service OS

This document builds on the Getting Started Guides, and explains how to use Ubuntu instead of using Clear Linux 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 Getting started guide for Intel NUC.

Install Ubuntu (natively)

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

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:

    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 Getting started guide for Intel NUC to install all the build tools and dependencies on your system.

  2. Clone the Project ACRN code repository

    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

  3. Build and install ACRN

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

    cd ~/acrn-hypervisor
make PLATFORM=uefi
sudo make install

    For more details, please refer to the Getting started guide for Intel NUC.

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

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

      ls /boot/efi/EFI/ubuntu/

      You should see the following output:

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

    2. Install the hypervisor (acrn.efi)

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

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

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

    4. Verify that the “ACRN Hypervisor” is added and make sure it will be booted first

      sudo efibootmgr -v

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

    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 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 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, 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

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

    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

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

    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/

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

      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 i915.nuclear_pageflip=1 root=PARTUUID=<UUID of rootfs partition> rw rootwait ignore_loglevel no_timer_check consoleblank=0 i915.tsd_init=7 i915.tsd_delay=2000 i915.avail_planes_per_pipe=0x01010F i915.domain_plane_owners=0x011111110000 i915.enable_guc_loading=0 i915.enable_guc_submission=0 i915.enable_preemption=1 i915.context_priority_mode=2 i915.enable_gvt=1 i915.enable_initial_modeset=1 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.

      #GRUB_TIMEOUT_STYLE=hidden
#GRUB_HIDDEN_TIMEOUT=0
GRUB_HIDDEN_TIMEOUT_QUIET=false

    • Update Grub on your system

      sudo update-grub

  5. 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 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:

    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 release version as the Service OS.

  • Download the Clear Linux image from https://download.clearlinux.org

    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

    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

    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:

    sudo chmod 777 /dev/acrn_vhm

  • One additional package is needed

    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:

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

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

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

taps=$(ifconfig | grep acrn_ | awk '{print $1}')

# 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
# add existing tap devices under the bridge
  for tap in $taps; do
    ip tuntap add dev acrn_$tap mode tap
    brctl addif acrn-br0 $tap
    ip link set dev $tap down
    ip link set dev $tap up
  done
fi

brctl addif acrn-br0 acrn_tap0
ip link set dev acrn_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 Getting started guide for Intel NUC for enabling the USB keyboard and mouse for the UOS.