Install ACRN Out of the Box

In this tutorial, we will learn to generate an out-of-the-box (OOTB) Service VM or a Preempt-RT VM image so that we can use ACRN or RTVM immediately after installation without any configuration or modification.

Set up a Build Environment

  1. Follow the Clear Linux OS installation guide to install a native Clear Linux OS on a development machine.

  2. Log in to the Clear Linux OS and install these bundles:

    $ sudo swupd bundle-add clr-installer vim network-basic

Generate a Service VM image

Step 1: Create a Service VM YAML file and script

Scenario 1: ACRN SDC

  1. Create the ACRN SDC service-os.yaml file:

    $ mkdir -p ~/service-os && cd ~/service-os
$ vim service-os.yaml

    Update the service-os.yaml file to:

    block-devices: [
   {name: "bdevice", file: "sos.img"}
]

targetMedia:
- name: ${bdevice}
  size: "108.54G"
  type: disk
  children:
  - name: ${bdevice}1
    fstype: vfat
    mountpoint: /boot
    size: "512M"
    type: part
  - name: ${bdevice}2
    fstype: swap
    size: "32M"
    type: part
  - name: ${bdevice}3
    fstype: ext4
    mountpoint: /
    size: "108G"
    type: part

bundles: [
    bootloader,
    editors,
    network-basic,
    openssh-server,
    os-core,
    os-core-update,
    sysadmin-basic,
    systemd-networkd-autostart,
    service-os
  ]

autoUpdate: false
postArchive: false
postReboot: false
telemetry: false
hostname: clr-sos

keyboard: us
language: en_US.UTF-8
kernel: kernel-iot-lts2018-sos

post-install: [
   {cmd: "${yamlDir}/service-os-post.sh ${chrootDir}"},
]

version: 32030

    Note

    Update the version value to your target Clear Linux version.

  2. Create the ACRN SDC service-os-post.sh script:

    $ vim service-os-post.sh

    Update the service-os-post.sh script to:

    #!/bin/bash
# Copyright (C) 2019 Intel Corporation.
# SPDX-License-Identifier: BSD-3-Clause

# ACRN SOS Image Post Install steps

set -ex

CHROOTPATH=$1

# acrn.efi path
acrn_efi_path="$CHROOTPATH/usr/lib/acrn/acrn.nuc7i7dnb.sdc.efi"

# copy acrn.efi to efi partition
mkdir -p "$CHROOTPATH/boot/EFI/acrn" || exit 1
cp "$acrn_efi_path" "$CHROOTPATH/boot/EFI/acrn/acrn.efi" || exit 1

# create load.conf
echo "Add default (5 seconds) boot wait time"
echo "timeout 5" >> "$CHROOTPATH/boot/loader/loader.conf" || exit 1

chroot $CHROOTPATH systemd-machine-id-setup
chroot $CHROOTPATH systemctl enable getty@tty1.service

echo "Welcome to the Clear Linux* ACRN SOS image!

Please login as root for the first time!

" >> $1/etc/issue

exit 0

    Grant execute permission to the script:

    $ chmod a+x service-os-post.sh

Scenario 2: ACRN INDUSTRY

  1. Create the ACRN INDUSTRY service-os-industry.yaml file:

    $ mkdir -p ~/service-os-industry && cd ~/service-os-industry
$ vim service-os-industry.yaml

    Update the service-os-industry.yaml file to:

    block-devices: [
   {name: "bdevice", file: "sos-industry.img"}
]

targetMedia:
- name: ${bdevice}
  size: "108.54G"
  type: disk
  children:
  - name: ${bdevice}1
    fstype: vfat
    mountpoint: /boot
    size: "512M"
    type: part
  - name: ${bdevice}2
    fstype: swap
    size: "32M"
    type: part
  - name: ${bdevice}3
    fstype: ext4
    mountpoint: /
    size: "108G"
    type: part

bundles: [
    bootloader,
    editors,
    network-basic,
    openssh-server,
    os-core,
    os-core-update,
    sysadmin-basic,
    systemd-networkd-autostart,
    service-os
  ]

autoUpdate: false
postArchive: false
postReboot: false
telemetry: false
hostname: clr-sos

keyboard: us
language: en_US.UTF-8
kernel: kernel-iot-lts2018-sos


post-install: [
   {cmd: "${yamlDir}/service-os-industry-post.sh ${chrootDir}"},
]

version: 32030

    Note

    Update the version value to your target Clear Linux version.

  2. Create the service-os-industry-post.sh script:

    $ vim service-os-industry-post.sh

    Update the service-os-industry-post.sh script to:

    #!/bin/bash
# Copyright (C) 2019 Intel Corporation.
# SPDX-License-Identifier: BSD-3-Clause


# ACRN SOS Image Post Install steps

set -ex

CHROOTPATH=$1

# acrn.nuc7i7dnb.industry.efi path
acrn_industry_efi_path="$CHROOTPATH/usr/lib/acrn/acrn.nuc7i7dnb.industry.efi"

# copy acrn.efi to efi partition
mkdir -p "$CHROOTPATH/boot/EFI/acrn" || exit 1
cp "$acrn_industry_efi_path" "$CHROOTPATH/boot/EFI/acrn/acrn.efi" || exit 1

# create load.conf
echo "Add default (5 seconds) boot wait time"
echo "timeout 5" >> "$CHROOTPATH/boot/loader/loader.conf" || exit 1

chroot $CHROOTPATH systemd-machine-id-setup
chroot $CHROOTPATH systemctl enable getty@tty1.service

echo "Welcome to the Clear Linux* ACRN SOS Industry image!

Please login as root for the first time!

" >> $1/etc/issue

exit 0

    Grant execute permission to the script:

    $ chmod a+x service-os-industry-post.sh

Step 2: Build the Service VM image

Use the clr-installer to build the Service VM image.

Scenario 1: ACRN SDC

$ cd ~/service-os
$ sudo clr-installer -c service-os.yaml

The sos.img will be generated at current directory.

Scenario 2: ACRN INDUSTRY

$ cd ~/service-os-industry
$ sudo clr-installer -c service-os-industry.yaml

The sos-industry.img will be generated at current directory.

Step 3: Deploy the Service VM image

  1. Prepare a U disk with at least 8GB memory. Begin by formatting the U disk:

    # sudo gdisk /dev/sdb
GPT fdisk (gdisk) version 1.0.3

Partition table scan:
  MBR: protective
  BSD: not present
  APM: not present
  GPT: present

Found valid GPT with protective MBR; using GPT.

Command (? for help): o
This option deletes all partitions and creates a new protective MBR.
Proceed? (Y/N): Y

Command (? for help): w

Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING
PARTITIONS!!

Do you want to proceed? (Y/N): Y
OK; writing new GUID partition table (GPT) to /dev/sdb.
The operation has completed successfully.

  2. Follow these steps to create two partitions on the U disk. Keep 4GB in the first partition and leave free space in the second partition.

    # sudo gdisk /dev/sdb
GPT fdisk (gdisk) version 1.0.3

Partition table scan:
  MBR: protective
  BSD: not present
  APM: not present
  GPT: present

Found valid GPT with protective MBR; using GPT.

Command (? for help): n
Partition number (1-128, default 1):
First sector (34-15249374, default = 2048) or {+-}size{KMGTP}:
Last sector (2048-15249374, default = 15249374) or {+-}size{KMGTP}: +4G
Current type is 'Linux filesystem'
Hex code or GUID (L to show codes, Enter = 8300):
Changed type of partition to 'Linux filesystem'

Command (? for help): n
Partition number (2-128, default 2):
First sector (34-15249374, default = 8390656) or {+-}size{KMGTP}:
Last sector (8390656-15249374, default = 15249374) or {+-}size{KMGTP}:
Current type is 'Linux filesystem'
Hex code or GUID (L to show codes, Enter = 8300):
Changed type of partition to 'Linux filesystem'

Command (? for help): p
Disk /dev/sdb: 15249408 sectors, 7.3 GiB
Model: USB FLASH DRIVE
Sector size (logical/physical): 512/512 bytes
Disk identifier (GUID): 8C6BF21D-521A-49D5-8BC8-5B319FAF3F91
Partition table holds up to 128 entries
Main partition table begins at sector 2 and ends at sector 33
First usable sector is 34, last usable sector is 15249374
Partitions will be aligned on 2048-sector boundaries
Total free space is 2014 sectors (1007.0 KiB)

Number  Start (sector)    End (sector)  Size       Code  Name
   1            2048         8390655   4.0 GiB     8300  Linux filesystem
   2         8390656        15249374   3.3 GiB     8300  Linux filesystem

Command (? for help): w

Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING
PARTITIONS!!

Do you want to proceed? (Y/N): Y
OK; writing new GUID partition table (GPT) to /dev/sdb.
The operation has completed successfully.

  3. Download and install a bootable Clear Linux on the U disk:

    $ wget https://download.clearlinux.org/releases/32030/clear/clear-32030-live-server.iso
$ sudo dd if=clear-32030-live-server.iso of=/dev/sdb1 bs=4M oflag=sync status=progress

  4. Copy the sos.img or sos-industry.img to the U disk:

    $ sudo mkfs.ext4 /dev/sdb2
$ sudo mount /dev/sdb2 /mnt

    • ACRN SDC scenario:

      $ cp ~/service-os/sos.img /mnt
$ sync && umount /mnt

    • ACRN INDUSTRY scenario:

      $ cp ~/service-os-industry/sos-industry.img /mnt
$ sync && umount /mnt

  5. Unplug the U disk from the development machine and plug it in to your test machine.

  6. Reboot the test machine and boot from the USB.

  7. Log in to the Live Service Clear Linux OS with your “root” account and mount the second partition on the U disk:

    # mount /dev/sdb2 /mnt

  8. Format the disk that will install the Service VM image:

    # sudo gdisk /dev/sda
GPT fdisk (gdisk) version 1.0.3

Partition table scan:
  MBR: protective
  BSD: not present
  APM: not present
  GPT: present

Found valid GPT with protective MBR; using GPT.

Command (? for help): o
This option deletes all partitions and creates a new protective MBR.
Proceed? (Y/N): Y

Command (? for help): w

Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING
PARTITIONS!!

Do you want to proceed? (Y/N): Y
OK; writing new GUID partition table (GPT) to /dev/sda.
The operation has completed successfully.

  9. Delete the old ACRN EFI firmware info:

    # efibootmgr | grep ACRN | cut -d'*' -f1 | cut -d't' -f2 | xargs -i efibootmgr -b {} -B

  10. Write the Service VM:

    • ACRN SDC scenario:

      # dd if=/mnt/sos.img of=/dev/sda bs=4M oflag=sync status=progress iflag=fullblock seek=0 conv=notrunc

    • ACRN INDUSTRY scenario:

      # dd if=/mnt/sos-industry.img of=/dev/sda bs=4M oflag=sync status=progress iflag=fullblock seek=0 conv=notrunc

Note

Given the large YAML size setting of over 100G, generating the Service VM image and writing it to disk will take some time.

  1. Configure the EFI firmware to boot the ACRN hypervisor by default:

    # efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN"

  2. Unplug the U disk and reboot the test machine. After the Clear Linux OS boots, log in as “root” for the first time.

Generate a User VM Preempt-RT image

Step 1: Create a Preempt-RT image YAML file and script

  1. Create the preempt-rt.yaml file:

    $ mkdir -p ~/preempt-rt && cd ~/preempt-rt
$ vim preempt-rt.yaml

    Update the preempt-rt.yaml file to:

    block-devices: [
   {name: "bdevice", file: "preempt-rt.img"}
]

targetMedia:
- name: ${bdevice}
  size: "8.54G"
  type: disk
  children:
  - name: ${bdevice}1
    fstype: vfat
    mountpoint: /boot
    size: "512M"
    type: part
  - name: ${bdevice}2
    fstype: swap
    size: "32M"
    type: part
  - name: ${bdevice}3
    fstype: ext4
    mountpoint: /
    size: "8G"
    type: part

bundles: [
    bootloader,
    editors,
    network-basic,
    openssh-server,
    os-core,
    os-core-update,
    sysadmin-basic,
    systemd-networkd-autostart
  ]

autoUpdate: false
postArchive: false
postReboot: false
telemetry: false
hostname: clr-preempt-rt

keyboard: us
language: en_US.UTF-8
kernel: kernel-lts2018-preempt-rt

version: 32030

    Note

    Update the version value to your target Clear Linux version

Step 2: Build a User VM Preempt-RT image

$ sudo clr-installer -c preempt-rt.yaml

The preempt-rt.img will be generated at the current directory.

Step 3: Deploy the User VM Preempt-RT image

  1. Log in to the Service VM and copy the preempt-rt.img from the development machine:

    $ mkdir -p preempt-rt && cd preempt-rt
$ scp <development username>@<development machine ip>:<path to preempt-rt.img> .

  2. Write preempt-rt.img to disk:

    $ sudo dd if=<path to preempt-rt.img> of=/dev/nvme0n1 bs=4M oflag=sync status=progress

  3. Launch the Preempt-RT User VM:

    $ sudo /usr/share/acrn/samples/nuc/launch_hard_rt_vm.sh