1.. _tar_installation:
2
3ACRN Installation via Tar Files
4####################################
5
6Project ACRN offers two ways to install ACRN on target systems, either via
7Debian packages or tar files. This document covers the tar file method. For
8information about the Debian method, see :ref:`debian_packaging`.
9
10Tar files provide a way to package ACRN configurations for Linux
11target systems running non-Debian operating systems. You generate the tar
12files on your development computer, copy them to your target system,
13extract the tar files to the right places,
14and reboot the system with ACRN up and running.
15
16This document shows examples of commands used to build and install the tar
17files. You might need to modify the commands for your environment.
18
19Prerequisites
20*************
21
22* A development computer configured according to the :ref:`gsg` (for example, it
23  has an Ubuntu OS, ACRN dependencies, and ACRN hypervisor and kernel source
24  code from the ACRN GitHub repository).
25
26Build the Tar Files
27***************************
28
29#. On your development computer, navigate to the ``acrn-hypervisor`` source code
30   directory and build the ACRN hypervisor tar files. Replace
31   ``<board.xml>`` and ``<scenario.xml>`` with the paths to your board
32   configuration file and scenario configuration file.
33
34   .. code-block:: bash
35
36      cd ~/acrn-work/acrn-hypervisor
37      make -j $(nproc) BOARD=<board.xml> SCENARIO=<scenario.xml>
38      make targz-pkg
39
40   The build typically takes a few minutes. By default, the build results are
41   found in the ``build`` directory.
42
43#. Navigate to the ``acrn-kernel`` source code directory and build the ACRN
44   kernel tar files for the Service VM:
45
46   .. code-block:: bash
47
48      cd ~/acrn-work/acrn-kernel
49      cp kernel_config_service_vm .config
50      make olddefconfig
51      make -j $(nproc) targz-pkg
52
53   The kernel build can take 15 minutes or less on a fast computer, but could
54   take an hour or more depending on the performance of your development
55   computer. By default, the build results are found in the current directory.
56
57Install and Run ACRN
58**************************
59
60In the following steps, you will install the tar files, install the serial
61configuration tool, configure GRUB, and run ACRN on the target system.
62
63#. Copy all the necessary files generated on the development computer to the
64   target system. The following steps show how to copy via USB disk; feel free
65   to use a different method. Modify the file names in the following commands to
66   match your files.
67
68   a. Insert the USB disk into the development computer and run these commands:
69
70      .. code-block:: bash
71
72         cd ~/acrn-work/acrn-kernel
73         disk="/media/$USER/"$(ls /media/$USER)
74         cp linux-5.10.90-acrn-service-vm-206626-g140f5035e1b1-x86.tar.gz "$disk"/
75         cp ~/acrn-work/acpica-unix-20210105/generate/unix/bin/iasl "$disk"/
76         cp ~/acrn-work/acrn-hypervisor/build/acrn-2.8-unstable.tar.gz "$disk"/
77         sync && sudo umount "$disk"/
78
79   #. Insert the USB disk you just used into the target system and run these
80      commands to copy the files locally:
81
82      .. code-block:: bash
83
84         disk="/media/$USER/"$(ls /media/$USER)
85         cp "$disk"/linux-5.10.90-acrn-service-vm-206626-g140f5035e1b1-x86.tar.gz ~/acrn-work
86         cp "$disk"/acrn-2.8-unstable.tar.gz ~/acrn-work
87         sudo cp "$disk"/iasl /usr/sbin/
88         sync && sudo umount "$disk"/
89
90#. Extract the Service VM files onto the target system:
91
92   .. code-block:: bash
93
94      cd ~/acrn-work
95      sudo tar -zxvf linux-5.10.90-acrn-service-vm-206626-g140f5035e1b1-x86.tar.gz -C / --keep-directory-symlink
96
97#. Extract the ACRN tools and images:
98
99   .. code-block:: bash
100
101      sudo tar -zxvf acrn-2.8-unstable.tar.gz -C / --keep-directory-symlink
102
103#. Copy the ACRN bin file to the boot directory. Replace ``<board>`` and
104   ``<scenario>`` to match your file.
105
106   .. code-block:: bash
107
108      sudo mkdir -p /boot/acrn/
109      sudo cp /usr/lib64/acrn/acrn.<board>.<scenario>.bin /boot/acrn
110
111#. Install the serial configuration tool in the target system as follows:
112
113   .. code-block:: bash
114
115      sudo apt install setserial
116
117#. Find the root filesystem (rootfs) device name by using the
118   ``lsblk`` command:
119
120   .. code-block:: console
121      :emphasize-lines: 24
122
123      ~$ lsblk
124      NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
125      loop0         7:0    0 255.6M  1 loop /snap/gnome-3-34-1804/36
126      loop1         7:1    0  62.1M  1 loop /snap/gtk-common-themes/1506
127      loop2         7:2    0   2.5M  1 loop /snap/gnome-calculator/884
128      loop3         7:3    0 241.4M  1 loop /snap/gnome-3-38-2004/70
129      loop4         7:4    0  61.8M  1 loop /snap/core20/1081
130      loop5         7:5    0   956K  1 loop /snap/gnome-logs/100
131      loop6         7:6    0   2.2M  1 loop /snap/gnome-system-monitor/148
132      loop7         7:7    0   2.4M  1 loop /snap/gnome-calculator/748
133      loop8         7:8    0  29.9M  1 loop /snap/snapd/8542
134      loop9         7:9    0  32.3M  1 loop /snap/snapd/12704
135      loop10        7:10   0  65.1M  1 loop /snap/gtk-common-themes/1515
136      loop11        7:11   0   219M  1 loop /snap/gnome-3-34-1804/72
137      loop12        7:12   0  55.4M  1 loop /snap/core18/2128
138      loop13        7:13   0  55.5M  1 loop /snap/core18/2074
139      loop14        7:14   0   2.5M  1 loop /snap/gnome-system-monitor/163
140      loop15        7:15   0   704K  1 loop /snap/gnome-characters/726
141      loop16        7:16   0   276K  1 loop /snap/gnome-characters/550
142      loop17        7:17   0   548K  1 loop /snap/gnome-logs/106
143      loop18        7:18   0 243.9M  1 loop /snap/gnome-3-38-2004/39
144      nvme0n1     259:0    0 119.2G  0 disk
145      ├─nvme0n1p1 259:1    0   512M  0 part /boot/efi
146      └─nvme0n1p2 259:2    0 118.8G  0 part /
147
148   As highlighted, you're looking for the device name associated with the
149   partition named ``/``, in this case ``nvme0n1p2``.
150
151#. Run the ``blkid`` command to get the UUID and PARTUUID for the rootfs device
152   (replace the ``nvme0n1p2`` name with the name shown for the rootfs on your
153   system):
154
155   .. code-block:: bash
156
157      sudo blkid /dev/nvme0n1p2
158
159   In the output, look for the UUID and PARTUUID (example below). You will need
160   them in the next step.
161
162   .. code-block:: console
163
164      /dev/nvme0n1p2: UUID="3cac5675-e329-4cal-b346-0a3e65f99016" TYPE="ext4" PARTUUID="03db7f45-8a6c-454b-adf7-30343d82c4f4"
165
166#. Add the ACRN Service VM to the GRUB boot menu:
167
168   a. Edit the GRUB ``40_custom`` file. The following command uses ``vi``, but
169      you can use any text editor.
170
171      .. code-block:: bash
172
173         sudo vi /etc/grub.d/40_custom
174
175   #. Add the following text at the end of the file. Replace ``UUID`` and
176      ``PARTUUID`` with the output from the previous step. Replace ``<board>``
177      and ``<scenario>`` to match your bin file. Confirm the module2 file name
178      matches the file in your ``boot`` directory.
179
180      .. code-block:: bash
181         :emphasize-lines: 6,8,9
182
183         menuentry "ACRN Multiboot Ubuntu Service VM" --id ubuntu-service-vm {
184           load_video
185           insmod gzio
186           insmod part_gpt
187           insmod ext2
188           search --no-floppy --fs-uuid --set "UUID"
189           echo 'loading ACRN...'
190           multiboot2 /boot/acrn/acrn.<board>.<scenario>.bin  root=PARTUUID="PARTUUID"
191           module2 /boot/vmlinuz-5.10.90-acrn-service-vm-206626-g140f5035e1b1 Linux_bzImage
192         }
193
194      Example:
195
196      .. code-block:: console
197
198         menuentry "ACRN Multiboot Ubuntu Service VM" --id ubuntu-service-vm {
199           load_video
200           insmod gzio
201           insmod part_gpt
202           insmod ext2
203           search --no-floppy --fs-uuid --set "3cac5675-e329-4cal-b346-0a3e65f99016"
204           echo 'loading ACRN...'
205           multiboot2 /boot/acrn/acrn.my_board.shared.bin  root=PARTUUID="03db7f45-8a6c-454b-adf7-30343d82c4f4"
206           module2 /boot/vmlinuz-5.10.90-acrn-service-vm-206626-g140f5035e1b1 Linux_bzImage
207         }
208
209   #. Save and close the file.
210
211#. Make the GRUB menu visible when
212   booting and make it load the Service VM kernel by default:
213
214   a. Edit the ``grub`` file:
215
216      .. code-block:: bash
217
218         sudo vi /etc/default/grub
219
220   #. Edit lines with these settings (comment out the ``GRUB_TIMEOUT_STYLE``
221      line). Leave other lines as they are:
222
223      .. code-block:: bash
224
225         GRUB_DEFAULT=ubuntu-service-vm
226         #GRUB_TIMEOUT_STYLE=hidden
227         GRUB_TIMEOUT=5
228
229   #. Save and close the file.
230
231#. Update GRUB and reboot the system:
232
233   .. code-block:: bash
234
235      sudo update-grub
236      reboot
237
238#. Confirm that you see the GRUB menu with the "ACRN Multiboot Ubuntu Service
239   VM" entry. Select it and proceed to booting ACRN. (It may be autoselected, in
240   which case it will boot with this option automatically in 5 seconds.)
241
242   .. code-block:: console
243      :emphasize-lines: 6
244
245                                GNU GRUB version 2.04
246      ────────────────────────────────────────────────────────────────────────────────
247      Ubuntu
248      Advanced options for Ubuntu
249      UEFI Firmware Settings
250      *ACRN Multiboot Ubuntu Service VM
251