Important

This is the latest documentation for the unstable development branch of Project ACRN (master).
Use the drop-down menu on the left to select documentation for a stable release such as v3.2 or v3.0.

ACRN Installation via Tar Files¶

Project ACRN offers two ways to install ACRN on target systems, either via Debian packages or tar files. This document covers the tar file method. For information about the Debian method, see ACRN Installation via Debian Packages.

Tar files provide a way to package ACRN configurations for Linux target systems running non-Debian operating systems. You generate the tar files on your development computer, copy them to your target system, extract the tar files to the right places, and reboot the system with ACRN up and running.

This document shows examples of commands used to build and install the tar files. You might need to modify the commands for your environment.

Prerequisites¶

A development computer configured according to the Getting Started Guide (for example, it has an Ubuntu OS, ACRN dependencies, and ACRN hypervisor and kernel source code from the ACRN GitHub repository).

Build the Tar Files¶

On your development computer, navigate to the acrn-hypervisor source code directory and build the ACRN hypervisor tar files. Replace <board.xml> and <scenario.xml> with the paths to your board configuration file and scenario configuration file.
```
cd ~/acrn-work/acrn-hypervisor
make -j $(nproc) BOARD=<board.xml> SCENARIO=<scenario.xml>
make targz-pkg
```
The build typically takes a few minutes. By default, the build results are found in the build directory.
Navigate to the acrn-kernel source code directory and build the ACRN kernel tar files for the Service VM:
```
cd ~/acrn-work/acrn-kernel
cp kernel_config_service_vm .config
make olddefconfig
make -j $(nproc) targz-pkg
```
The kernel build can take 15 minutes or less on a fast computer, but could take an hour or more depending on the performance of your development computer. By default, the build results are found in the current directory.

Install and Run ACRN¶

In the following steps, you will install the tar files, install the serial configuration tool, configure GRUB, and run ACRN on the target system.

Copy all the necessary files generated on the development computer to the target system. The following steps show how to copy via USB disk; feel free to use a different method. Modify the file names in the following commands to match your files.

Insert the USB disk into the development computer and run these commands:

cd ~/acrn-work/acrn-kernel
disk="/media/$USER/"$(ls /media/$USER)
cp linux-5.10.90-acrn-service-vm-206626-g140f5035e1b1-x86.tar.gz "$disk"/
cp ~/acrn-work/acpica-unix-20210105/generate/unix/bin/iasl "$disk"/
cp ~/acrn-work/acrn-hypervisor/build/acrn-2.8-unstable.tar.gz "$disk"/
sync && sudo umount "$disk"/

Insert the USB disk you just used into the target system and run these commands to copy the files locally:

disk="/media/$USER/"$(ls /media/$USER)
cp "$disk"/linux-5.10.90-acrn-service-vm-206626-g140f5035e1b1-x86.tar.gz ~/acrn-work
cp "$disk"/acrn-2.8-unstable.tar.gz ~/acrn-work
sudo cp "$disk"/iasl /usr/sbin/
sync && sudo umount "$disk"/

Extract the Service VM files onto the target system:

cd ~/acrn-work
sudo tar -zxvf linux-5.10.90-acrn-service-vm-206626-g140f5035e1b1-x86.tar.gz -C / --keep-directory-symlink

Extract the ACRN tools and images:

sudo tar -zxvf acrn-2.8-unstable.tar.gz -C / --keep-directory-symlink

Copy the ACRN bin file to the boot directory. Replace <board> and <scenario> to match your file.
```
sudo mkdir -p /boot/acrn/
sudo cp /usr/lib64/acrn/acrn.<board>.<scenario>.bin /boot/acrn
```
Install the serial configuration tool in the target system as follows:
```
sudo apt install setserial
```

Find the root filesystem (rootfs) device name by using the lsblk command:

~$ lsblk
NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
loop0         7:0    0 255.6M  1 loop /snap/gnome-3-34-1804/36
loop1         7:1    0  62.1M  1 loop /snap/gtk-common-themes/1506
loop2         7:2    0   2.5M  1 loop /snap/gnome-calculator/884
loop3         7:3    0 241.4M  1 loop /snap/gnome-3-38-2004/70
loop4         7:4    0  61.8M  1 loop /snap/core20/1081
loop5         7:5    0   956K  1 loop /snap/gnome-logs/100
loop6         7:6    0   2.2M  1 loop /snap/gnome-system-monitor/148
loop7         7:7    0   2.4M  1 loop /snap/gnome-calculator/748
loop8         7:8    0  29.9M  1 loop /snap/snapd/8542
loop9         7:9    0  32.3M  1 loop /snap/snapd/12704
loop10        7:10   0  65.1M  1 loop /snap/gtk-common-themes/1515
loop11        7:11   0   219M  1 loop /snap/gnome-3-34-1804/72
loop12        7:12   0  55.4M  1 loop /snap/core18/2128
loop13        7:13   0  55.5M  1 loop /snap/core18/2074
loop14        7:14   0   2.5M  1 loop /snap/gnome-system-monitor/163
loop15        7:15   0   704K  1 loop /snap/gnome-characters/726
loop16        7:16   0   276K  1 loop /snap/gnome-characters/550
loop17        7:17   0   548K  1 loop /snap/gnome-logs/106
loop18        7:18   0 243.9M  1 loop /snap/gnome-3-38-2004/39
nvme0n1     259:0    0 119.2G  0 disk
├─nvme0n1p1 259:1    0   512M  0 part /boot/efi
└─nvme0n1p2 259:2    0 118.8G  0 part /

As highlighted, you’re looking for the device name associated with the partition named /, in this case nvme0n1p2.

Run the blkid command to get the UUID and PARTUUID for the rootfs device (replace the nvme0n1p2 name with the name shown for the rootfs on your system):
```
sudo blkid /dev/nvme0n1p2
```
In the output, look for the UUID and PARTUUID (example below). You will need them in the next step.
```
/dev/nvme0n1p2: UUID="3cac5675-e329-4cal-b346-0a3e65f99016" TYPE="ext4" PARTUUID="03db7f45-8a6c-454b-adf7-30343d82c4f4"
```

Add the ACRN Service VM to the GRUB boot menu:

Edit the GRUB 40_custom file. The following command uses vi, but you can use any text editor.
```
sudo vi /etc/grub.d/40_custom
```

Add the following text at the end of the file. Replace UUID and PARTUUID with the output from the previous step. Replace <board> and <scenario> to match your bin file. Confirm the module2 file name matches the file in your boot directory.

menuentry "ACRN Multiboot Ubuntu Service VM" --id ubuntu-service-vm {
  load_video
  insmod gzio
  insmod part_gpt
  insmod ext2
  search --no-floppy --fs-uuid --set "UUID"
  echo 'loading ACRN...'
  multiboot2 /boot/acrn/acrn.<board>.<scenario>.bin  root=PARTUUID="PARTUUID"
  module2 /boot/vmlinuz-5.10.90-acrn-service-vm-206626-g140f5035e1b1 Linux_bzImage
}

Example:

menuentry "ACRN Multiboot Ubuntu Service VM" --id ubuntu-service-vm {
  load_video
  insmod gzio
  insmod part_gpt
  insmod ext2
  search --no-floppy --fs-uuid --set "3cac5675-e329-4cal-b346-0a3e65f99016"
  echo 'loading ACRN...'
  multiboot2 /boot/acrn/acrn.my_board.shared.bin  root=PARTUUID="03db7f45-8a6c-454b-adf7-30343d82c4f4"
  module2 /boot/vmlinuz-5.10.90-acrn-service-vm-206626-g140f5035e1b1 Linux_bzImage
}

Save and close the file.

Make the GRUB menu visible when booting and make it load the Service VM kernel by default:
1. Edit the grub file:
```
sudo vi /etc/default/grub
```
2. Edit lines with these settings (comment out the GRUB_TIMEOUT_STYLE line). Leave other lines as they are:
```
GRUB_DEFAULT=ubuntu-service-vm
#GRUB_TIMEOUT_STYLE=hidden
GRUB_TIMEOUT=5
```
3. Save and close the file.
Update GRUB and reboot the system:
```
sudo update-grub
reboot
```

Confirm that you see the GRUB menu with the “ACRN Multiboot Ubuntu Service VM” entry. Select it and proceed to booting ACRN. (It may be autoselected, in which case it will boot with this option automatically in 5 seconds.)

                          GNU GRUB version 2.04
────────────────────────────────────────────────────────────────────────────────
Ubuntu
Advanced options for Ubuntu
UEFI Firmware Settings
*ACRN Multiboot Ubuntu Service VM