1.. _using_ubuntu_as_user_vm:
2
3Run Ubuntu as the User VM OS
4############################
5
6Prerequisites
7*************
8
9.. _Ubuntu 20.04 desktop ISO:
10   http://releases.ubuntu.com/focal/ubuntu-20.04.4-desktop-amd64.iso
11
12This tutorial assumes you have already set up the ACRN Service VM on your target
13system following the instructions in the :ref:`gsg`.
14
15Install these KVM tools on your development system:
16
17.. code-block:: none
18
19   sudo apt install qemu-kvm libvirt-clients libvirt-daemon-system bridge-utils virt-manager ovmf
20
21Validated Versions
22==================
23
24-  **Ubuntu version:** 20.04
25-  **ACRN hypervisor tag:** v3.0
26-  **Service VM Kernel version:** release_3.0
27
28.. _build-the-ubuntu-kvm-image:
29
30Build the Ubuntu KVM Image
31**************************
32
33This tutorial uses the Ubuntu 20.04 desktop ISO as the base image.
34
35#. Download the `Ubuntu 20.04 desktop ISO`_ on your development machine:
36
37#. Install Ubuntu via the virt-manager tool:
38
39   .. code-block:: none
40
41      sudo virt-manager
42
43#. Verify that you can see the main menu as shown in :numref:`vmmanager-ubun` below.
44
45   .. figure:: images/ubuntu_uservm_01.png
46      :align: center
47      :name: vmmanager-ubun
48      :class: drop-shadow
49
50      Virtual Machine Manager
51
52#. Right-click **QEMU/KVM** and select **New**.
53
54   a. Choose **Local install media (ISO image or CD-ROM)** and then click
55      **Forward**.
56
57      .. figure:: images/ubuntu_uservm_02.png
58         :align: center
59         :name: vmmanager-local-install
60         :class: drop-shadow
61
62         Choosing Local install media
63
64      A **Create a new virtual machine** box displays. Click **Browse** and
65      select the Ubuntu ISO file that you downloaded earlier.
66      If not already auto selected, choose the **OS type:** Linux, **Version:**
67      Ubuntu 20.04 LTS and then click **Forward**.
68
69      .. figure:: images/ubuntu_uservm_03.png
70         :align: center
71         :name: newVM-ubun-image
72         :class: drop-shadow
73
74         Select Ubuntu ISO file previously downloaded
75
76   #. Choose **Enable storage** and **Create a disk image for the virtual machine**.
77      Set the storage to 20 GB or more if necessary and click **Forward**.
78
79      .. figure:: images/ubuntu_uservm_storage.png
80         :align: center
81         :name: newVM-ubun-storage
82         :class: drop-shadow
83
84         Select VM disk storage
85
86   #. Rename the image if you desire. Check the
87      **customize configuration before install** option before you finish all stages.
88
89      .. figure:: images/ubuntu_uservm_customize.png
90         :align: center
91         :name: newVM-ubun-customize
92         :class: drop-shadow
93
94         Ready to customize image
95
96#. Verify the Firmware and Chipset settings are as shown in this Overview screen:
97
98   .. figure:: images/ubuntu_uservm_begin_install.png
99      :align: center
100      :name: ubun-begin-install
101      :class: drop-shadow
102
103      Ready to begin installation
104
105#. Click **Apply** and **Begin Installation** (in the top left corner). Complete
106   the normal Ubuntu installation within the QEMU emulator. Verify that you have
107   set up the disk partition as follows:
108
109   - /dev/vda1: EFI System Partition
110   - /dev/vda2: File System Partition
111
112#. Upon installation completion, click **Restart** Now to make sure the Ubuntu
113   OS boots successfully. Save the QEMU state and exit.
114
115#. The KVM image is created in the ``/var/lib/libvirt/images`` folder.
116   Convert the ``qcow2`` format to ``img`` **as the root user**:
117
118   .. code-block:: none
119
120      cd ~ && mkdir ubuntu_images && cd ubuntu_images
121      sudo qemu-img convert -f qcow2 -O raw /var/lib/libvirt/images/ubuntu20.04.qcow2 ubuntu_uservm.img
122
123
124Launch the Ubuntu Image as the User VM
125**************************************
126
127In the :ref:`gsg`, we used the ACRN configurator to create a scenario with a
128Service VM and an Ubuntu **ISO** image for the post-launched User VM.  We can use
129that same scenario with a slight edit for the User VM image name by changing
130the file name in the Virtio block device for the post-launched User VM.
131
1321. Change the virtio block device to use the new Ubuntu image we created using
133   KVM above:
134
135   .. figure:: images/ubuntu_uservm_virtioblock.png
136      :align: center
137      :name: ubun-virtio-block
138      :class: drop-shadow
139
140      Update virtio block device with image location
141
142   Then save this new configuration and write out the updated launch script.
143
144#. Copy the ``ubuntu_uservm.img`` and the updated launch script from the
145   development system to your target system.  For example, if the development
146   and target systems are on the same network, you could use ``scp``:
147
148   .. code-block:: none
149
150      scp ~/ubuntu_images/ubuntu_uservm.img ~/acrn-work/MyConfiguration/launch_user_vm_id1.sh user_name@ip_address:~/acrn-work/
151
152#. On the target system, launch the Ubuntu User VM after logging in to the Service VM:
153
154   .. code-block:: none
155
156      cd ~/acrn-work
157      sudo launch_user_vm_id1.sh
158
159