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: 31670
    

    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: 31670
    

    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 parition.

    # 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/31670/clear/clear-31670-live-server.iso
    $ sudo dd if=clear-31670-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
      
    • ACRN INDUSTRY scenario:

      # dd if=/mnt/sos-industry.img of=/dev/sda bs=4M oflag=sync status=progress
      
  11. 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"
    
  12. 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: 31670
    

    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