github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-07-18 17:33:43 +00:00
Code Issues Projects Releases Wiki Activity

Edits to Ubuntu SOS; changed SOS/UOS to Service VM/User VM

Browse Source 
Signed-off-by: Deb Taylor <deb.taylor@intel.com>
This commit is contained in:
Deb Taylor 2020-02-10 12:03:43 -05:00 committed by deb-intel
parent f3249e77bd
commit 7d4b2c824f
1 changed files with 106 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

207
doc/tutorials/using_ubuntu_as_sos.rst
View File

@ -1,19 +1,19 @@
.. _Ubuntu Service OS: .. _Ubuntu Service OS:
Using Ubuntu as the Service OS Running Ubuntu in the Service VM
############################## ################################
This document builds on the :ref:`getting_started`, and explains how to use This document builds on the :ref:`getting_started` series and explains how
Ubuntu instead of using `Clear Linux OS`_ as the Service OS with the ACRN to use Ubuntu instead of `Clear Linux OS`_ as the Service VM with the ACRN
hypervisor. (Note that different OSes can be used for the Service and User OS.) hypervisor. (Note that different OSs can be used for the Service and User
In the following instructions we'll build on material in the VM.) In the following instructions, we will build on material described in
:ref:`kbl-nuc-sdc`. :ref:`kbl-nuc-sdc`.
Install Ubuntu (natively) Install Ubuntu (natively)
************************* *************************
Ubuntu 18.04.1 LTS was used throughout this document, other older versions such as Ubuntu 18.04.1 LTS is used throughout this document; other older versions
16.04 works too. such as 16.04 also work.
* Download Ubuntu 18.04 from the `Ubuntu 18.04.1 LTS (Bionic Beaver) page * 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/>`_ and select the `ubuntu-18.04.1-desktop-amd64.iso
@ -22,12 +22,12 @@ Ubuntu 18.04.1 LTS was used throughout this document, other older versions such
* Follow Ubuntu's `online instructions <https://tutorials.ubuntu.com/tutorial/tutorial-install-ubuntu-desktop>`_ * Follow Ubuntu's `online instructions <https://tutorials.ubuntu.com/tutorial/tutorial-install-ubuntu-desktop>`_
to install it on your device. to install it on your device.
.. note:: .. note::
Configure your device's proxy settings to have full internet access. Configure your device's proxy settings to have full internet access.
* While not strictly required, enabling SSH gives the user a very useful * 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 mechanism for accessing the Service VM remotely or when running one or more
User OS (UOS). Follow these steps to enable it on the Ubuntu SOS: User VM. Follow these steps to enable it on the Ubuntu Service VM:
.. code-block:: none .. code-block:: none
@ -35,7 +35,7 @@ Ubuntu 18.04.1 LTS was used throughout this document, other older versions such
sudo service ssh status sudo service ssh status
sudo service ssh start sudo service ssh start
* If you want to SSH ubuntu as root, you will also need to modify ``/etc/ssh/sshd_config``: * If you plan to SSH Ubuntu as root, you must also modify ``/etc/ssh/sshd_config``:
.. code-block:: none .. code-block:: none
@ -44,16 +44,18 @@ Ubuntu 18.04.1 LTS was used throughout this document, other older versions such
Install ACRN Install ACRN
************ ************
ACRN components are distributed in source form, so you'll need to download ACRN components are distributed in source form, so you must download
the source code, build it, and install it on your device. the source code, build it, and install it on your device.
1. Install the build tools and dependencies 1. Install the build tools and dependencies.
Follow the instructions found in the :ref:`getting-started-building` to Follow the instructions found in :ref:`getting-started-building` to
install all the build tools and dependencies on your system. install all the build tools and dependencies on your system.
#. Clone the `Project ACRN <https://github.com/projectacrn/acrn-hypervisor>`_ #. Clone the `Project ACRN <https://github.com/projectacrn/acrn-hypervisor>`_
code repository code repository.
Enter the following:
.. code-block:: none .. code-block:: none
@ -62,13 +64,13 @@ the source code, build it, and install it on your device.
git checkout acrn-2019w47.1-140000p git checkout acrn-2019w47.1-140000p
.. note:: .. note::
We clone the git repository above but it is also possible to download the We clone the git repository above but it is also possible to download
tarball for any specific tag or release from the `Project ACRN Github the tarball for any specific tag or release from the `Project ACRN
release page <https://github.com/projectacrn/acrn-hypervisor/releases>`_ Github release page <https://github.com/projectacrn/acrn-hypervisor/releases>`_.
#. Build and install ACRN #. Build and install ACRN.
Here is the short version of how to build and install ACRN from source. Here is the short version on how to build and install ACRN from source:
.. code-block:: none .. code-block:: none
@ -76,17 +78,17 @@ the source code, build it, and install it on your device.
make make
sudo make install sudo make install
For more details, please refer to the :ref:`getting-started-building`. For more details, refer to :ref:`getting-started-building`.
#. Install the hypervisor #. Install the hypervisor.
The ACRN devicemodel and tools were installed as part of the previous step. The ACRN device model and tools are installed as part of the previous
However, ``make install`` does not install the hypervisor (``acrn.efi``) on 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 your EFI System Partition (ESP), nor does it configure your EFI firmware
boot it automatically. Follow the steps below to perform these operations to boot it automatically. Therefore, follow the steps below to perform
and complete the ACRN installation. these operations and complete the ACRN installation.
#. Add the ACRN hypervisor and Service OS kernel to it (as ``root``) #. Add the ACRN hypervisor and Service VM kernel to it (as ``root``):
.. code-block:: none .. code-block:: none
@ -98,14 +100,14 @@ the source code, build it, and install it on your device.
fw fwupx64.efi grub.cfg grubx64.efi MokManager.efi shimx64.efi fw fwupx64.efi grub.cfg grubx64.efi MokManager.efi shimx64.efi
#. Install the hypervisor (``acrn.efi``) #. Install the hypervisor (``acrn.efi``):
.. code-block:: none .. code-block:: none
sudo mkdir /boot/efi/EFI/acrn/ sudo mkdir /boot/efi/EFI/acrn/
sudo cp ~/acrn-hypervisor/build/hypervisor/acrn.efi /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 #. Configure the EFI firmware to boot the ACRN hypervisor by default:
.. code-block:: none .. code-block:: none
@ -116,39 +118,35 @@ the source code, build it, and install it on your device.
sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/nvme0n1 -p 1 \ sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/nvme0n1 -p 1 \
-L "ACRN Hypervisor" -u "bootloader=\EFI\ubuntu\grubx64.efi" -L "ACRN Hypervisor" -u "bootloader=\EFI\ubuntu\grubx64.efi"
#. Verify that the "ACRN Hypervisor" is added and make sure it will be booted first #. Verify that "ACRN Hypervisor" is added and that it will boot first:
.. code-block:: none .. code-block:: none
sudo efibootmgr -v sudo efibootmgr -v
#. You can change the boot order at any time using ``efibootmgr -o XXX,XXX,XXX`` You can also verify it by entering the EFI firmware at boot (using :kbd:`F10`).
#. Change the boot order at any time using ``efibootmgr -o XXX,XXX,XXX``:
.. code-block:: none .. code-block:: none
sudo efibootmgr -o xxx,xxx,xxx sudo efibootmgr -o xxx,xxx,xxx
.. note:: Install the Service VM kernel
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 Download the latest Service VM kernel.
`<https://download.clearlinux.org/releases/current/clear/x86_64/os/Packages/>`_
1. The latest Service OS kernel from the latest Clear Linux OS release 1. The latest Service VM kernel from the latest Clear Linux OS release is
from this area: located here: https://download.clearlinux.org/releases/current/clear/x86_64/os/Packages. Look for the following ``.rpm`` file:
https://download.clearlinux.org/releases/current/clear/x86_64/os/Packages. Look for an ``linux-iot-lts2018-sos-<kernel-version>-<build-version>.x86_64.rpm``.
``.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 While we recommend using the current (latest) Clear Linux OS release, you
a specific Clear Linux release from an area with that release number, e.g.: can download a specific Clear Linux release from an area with that
release number, such as the following:
https://download.clearlinux.org/releases/31670/clear/x86_64/os/Packages/linux-iot-lts2018-sos-4.19.78-98.x86_64.rpm https://download.clearlinux.org/releases/31670/clear/x86_64/os/Packages/linux-iot-lts2018-sos-4.19.78-98.x86_64.rpm
#. Download and extract the latest Service OS kernel(this guide is based on 31670 as the current example) #. Download and extract the latest Service VM kernel (this guide uses 31670 as the current example):
.. code-block:: none .. code-block:: none
@ -158,7 +156,7 @@ You can download latest Service OS kernel from
sudo apt-get install rpm2cpio sudo apt-get install rpm2cpio
rpm2cpio linux-iot-lts2018-sos-4.19.78-98.x86_64.rpm | cpio -idmv rpm2cpio linux-iot-lts2018-sos-4.19.78-98.x86_64.rpm | cpio -idmv
#. Install the SOS kernel and its drivers (modules) #. Install the Service VM kernel and its drivers (modules):
.. code-block:: none .. code-block:: none
@ -166,14 +164,14 @@ You can download latest Service OS kernel from
sudo mkdir /boot/acrn/ sudo mkdir /boot/acrn/
sudo cp ~/sos-kernel-build/usr/lib/kernel/org.clearlinux.iot-lts2018-sos.4.19.78-98 /boot/acrn/ sudo cp ~/sos-kernel-build/usr/lib/kernel/org.clearlinux.iot-lts2018-sos.4.19.78-98 /boot/acrn/
#. Configure Grub to load the Service OS kernel #. Configure Grub to load the Service VM kernel:
* Modify the ``/etc/grub.d/40_custom`` file to create a new Grub entry that * Modify the ``/etc/grub.d/40_custom`` file to create a new Grub entry
will boot the SOS kernel. that will boot the Service VM kernel.
.. code-block:: none .. code-block:: none
menuentry 'ACRN ubuntu SOS' --id ubuntu-service-vm { menuentry 'ACRN Ubuntu Service VM' --id ubuntu-service-vm {
recordfail recordfail
load_video load_video
insmod gzio insmod gzio
@ -183,20 +181,19 @@ You can download latest Service OS kernel from
} }
.. note:: .. note::
You need to adjust this to use your partition UUID (``PARTUUID``) for Adjust this to use your partition UUID (``PARTUUID``) for the
the ``root=`` parameter (or use the device node directly). ``root=`` parameter (or use the device node directly).
.. note:: Adjust the kernel name if you used a different RPM file as the
You will also need to adjust the kernel name if you used a different source of your Service VM kernel.
RPM file as the source of your Service OS kernel.
.. note:: The command line for the kernel in ``/etc/grub.d/40_custom``
The command line for the kernel in /etc/grub.d/40_custom should be all should be entered as a single line, not as multiple lines.
as a single line, not as multiple lines. Otherwise the kernel will fail to boot Otherwise, the kernel will fail to boot.
* Modify the ``/etc/default/grub`` file to make the grub menu visible when booting * Modify the ``/etc/default/grub`` file to make the grub menu visible
and make it load the Service OS kernel by default. when booting and make it load the Service VM kernel by default.
There are a few lines to be modified, as shown below. Modify the lines shown below:
.. code-block:: none .. code-block:: none
@ -204,29 +201,29 @@ You can download latest Service OS kernel from
#GRUB_TIMEOUT_STYLE=hidden #GRUB_TIMEOUT_STYLE=hidden
GRUB_TIMEOUT=3 GRUB_TIMEOUT=3
* Update Grub on your system * Update Grub on your system:
.. code-block:: none .. code-block:: none
sudo update-grub sudo update-grub
#. Reboot the system #. Reboot the system.
Reboot system. You should see the Grub menu with the new "ACRN ubuntu SOS" Reboot the system. You should see the Grub menu with the new ACRN ``ubuntu-service-vm``
entry. Select it and proceed to booting the platform. The system will start entry. Select it and proceed to booting the platform. The system will
the Ubuntu Desktop and you can now log in (as before). start the Ubuntu Desktop and you can now log in (as before).
.. note:: .. note::
If you don't see the Grub menu after rebooting the system (and you're If you don't see the Grub menu after rebooting the system (and you are
not booting into the ACRN hypervisor), you'll need to enter the not booting into the ACRN hypervisor), enter the EFI firmware at boot
EFI firmware at boot (using :kbd:`F10`) and manually select ``ACRN Hypervisor``. (using :kbd:`F10`) and manually select ``ACRN Hypervisor``.
.. note:: If you see a black screen on the first-time reboot after installing
If you see a black screen on the first-time reboot after installing the ACRN Hypervisor, the ACRN Hypervisor, wait a few moments and the Ubuntu desktop will
wait a few moments and the Ubuntu desktop will be displayed. display.
To check if the hypervisor is effectively running, check ``dmesg``. The To verify that the hypervisor is effectively running, check ``dmesg``. The
typical output of a successful installation will look like this: typical output of a successful installation resembles the following:
.. code-block:: none .. code-block:: none
@ -236,12 +233,13 @@ You can download latest Service OS kernel from
.. _prepare-UOS: .. _prepare-UOS:
Prepare the User OS (UOS) Prepare the User VM
************************* *******************
For the User OS, we are using the same `Clear Linux OS`_ release version as the Service OS. For the User VM, we are using the same `Clear Linux OS`_ release version as
for the Service VM.
* Download the Clear Linux OS image from `<https://download.clearlinux.org>`_ * Download the Clear Linux OS image from `<https://download.clearlinux.org>`_:
.. code-block:: none .. code-block:: none
@ -249,7 +247,7 @@ For the User OS, we are using the same `Clear Linux OS`_ release version as the
wget https://download.clearlinux.org/releases/31670/clear/clear-31670-kvm.img.xz wget https://download.clearlinux.org/releases/31670/clear/clear-31670-kvm.img.xz
unxz clear-31670-kvm.img.xz unxz clear-31670-kvm.img.xz
* Download the "kernel-iot-lts2018" kernel * Download the "linux-iot-lts2018" kernel:
.. code-block:: none .. code-block:: none
@ -258,7 +256,7 @@ For the User OS, we are using the same `Clear Linux OS`_ release version as the
wget https://download.clearlinux.org/releases/31670/clear/x86_64/os/Packages/linux-iot-lts2018-sos-4.19.78-98.x86_64.rpm wget https://download.clearlinux.org/releases/31670/clear/x86_64/os/Packages/linux-iot-lts2018-sos-4.19.78-98.x86_64.rpm
rpm2cpio linux-iot-lts2018-4.19.78-98.x86_64.rpm | cpio -idmv rpm2cpio linux-iot-lts2018-4.19.78-98.x86_64.rpm | cpio -idmv
* Update the UOS kernel modules * Update the User VM kernel modules:
.. code-block:: none .. code-block:: none
@ -275,7 +273,7 @@ For the User OS, we are using the same `Clear Linux OS`_ release version as the
sudo chmod 777 /dev/acrn_vhm sudo chmod 777 /dev/acrn_vhm
* One additional package is needed * Add the following package:
.. code-block:: none .. code-block:: none
@ -289,38 +287,38 @@ For the User OS, we are using the same `Clear Linux OS`_ release version as the
sudo cp ./generate/unix/bin/iasl /usr/sbin/ sudo cp ./generate/unix/bin/iasl /usr/sbin/
* Adjust ``launch_uos.sh`` * Adjust the ``launch_uos.sh`` script:
You need to adjust the ``/usr/share/acrn/samples/nuc/launch_uos.sh`` script 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: to match your installation. Modify the following lines:
.. code-block:: none .. code-block:: none
-s 3,virtio-blk,/root/clear-31670-kvm.img \ -s 3,virtio-blk,/root/clear-31670-kvm.img \
.. note:: .. note::
The image of UOS can be stored in other directories instead of ``~/``, The User VM image can be stored in other directories instead of ``~/``.
and please remember to modify the directory of image in ``launch_uos.sh`` too. Remember to also modify the image directory in ``launch_uos.sh``.
Start the User OS (UOS) Start the User VM
*********************** *****************
You are now all set to start the User OS (UOS) You are now all set to start the User VM:
.. code-block:: none .. code-block:: none
sudo /usr/share/acrn/samples/nuc/launch_uos.sh sudo /usr/share/acrn/samples/nuc/launch_uos.sh
**Congratulations**, you are now watching the User OS booting up! **Congratulations**, you are now watching the User VM booting up!
Enabling network sharing Enable 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).
After booting up the Service VM and User VM, network sharing must be enabled
to give network access to the Service VM by enabling the TAP and networking
bridge in the Service VM. The following script example shows how to set
this up (verified in Ubuntu 16.04 and 18.04 as the Service VM).
.. code-block:: none .. code-block:: none
@ -344,14 +342,15 @@ script example shows how to set this up (verified in Ubuntu 16.04 and 18.04 as t
ip link set dev tap0 up ip link set dev tap0 up
.. note:: .. note::
The SOS network interface is called ``enp3s0`` in the script above. You will need The Service VM network interface is called ``enp3s0`` in the script
to adjust the script if your system uses a different name (e.g. ``eno1``). above. Adjust the script if your system uses a different name (e.g.
``eno1``).
Enabling USB keyboard and mouse Enable the USB keyboard and mouse
******************************* *********************************
Please refer to :ref:`kbl-nuc-sdc` for enabling the Refer to :ref:`kbl-nuc-sdc` for instructions on enabling the USB keyboard
USB keyboard and mouse for the UOS. and mouse for the User VM.
.. _Clear Linux OS: https://clearlinux.org .. _Clear Linux OS: https://clearlinux.org