2019-09-26 07:20:20 +08:00
.. _acrn_ootb:
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
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
***** ***** ***** ***** ***** *
2019-09-24 23:47:57 +08:00
#. Follow the `Clear Linux OS installation guide
2020-03-19 04:32:45 +08:00
<https://docs.01.org/clearlinux/latest/get-started/bare-metal-install-server.html>`_
2019-09-26 07:20:20 +08:00
to install a native Clear Linux OS on a development machine.
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
#. Log in to the Clear Linux OS and install these bundles::
2019-09-24 23:47:57 +08:00
$ sudo swupd bundle-add clr-installer vim network-basic
.. _set_up_ootb_service_vm:
2019-09-26 07:20:20 +08:00
Generate a Service VM image
***** ***** ***** ***** ***** **
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
Step 1: Create a Service VM YAML file and script
================================================
**Scenario 1: ACRN SDC**
2019-09-24 23:47:57 +08:00
#. Create the ACRN SDC `` service-os.yaml `` file:
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
$ mkdir -p ~/service-os && cd ~/service-os
$ vim service-os.yaml
2019-09-26 07:20:20 +08:00
Update the `` service-os.yaml `` file to:
2019-09-24 23:47:57 +08:00
.. code-block :: bash
:emphasize-lines: 51
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
block-devices: [
{name: "bdevice", file: "sos.img"}
]
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
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
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
bundles: [
bootloader,
editors,
network-basic,
openssh-server,
os-core,
os-core-update,
sysadmin-basic,
systemd-networkd-autostart,
service-os
]
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
autoUpdate: false
postArchive: false
postReboot: false
telemetry: false
hostname: clr-sos
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
keyboard: us
language: en_US.UTF-8
kernel: kernel-iot-lts2018-sos
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
post-install: [
{cmd: "${yamlDir}/service-os-post.sh ${chrootDir}"},
]
2019-09-26 07:20:20 +08:00
2020-01-08 16:33:21 +08:00
version: 32030
2019-09-26 07:20:20 +08:00
.. note :: Update the version value to your target Clear Linux version.
#. Create the ACRN SDC `` service-os-post.sh `` script:
.. code-block :: none
2019-09-24 23:47:57 +08:00
$ vim service-os-post.sh
2019-09-26 07:20:20 +08:00
Update the `` service-os-post.sh `` script to:
2019-09-24 23:47:57 +08:00
.. code-block :: bash
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
#!/bin/bash
2019-11-12 09:33:14 +08:00
# Copyright (C) 2019 Intel Corporation.
# SPDX-License-Identifier: BSD-3-Clause
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
# ACRN SOS Image Post Install steps
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
set -ex
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
CHROOTPATH=$1
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
# acrn.efi path
2019-11-12 09:33:14 +08:00
acrn_efi_path="$CHROOTPATH/usr/lib/acrn/acrn.nuc7i7dnb.sdc.efi"
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
# copy acrn.efi to efi partition
mkdir -p "$CHROOTPATH/boot/EFI/acrn" || exit 1
2019-11-12 09:33:14 +08:00
cp "$acrn_efi_path" "$CHROOTPATH/boot/EFI/acrn/acrn.efi" || exit 1
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
# create load.conf
echo "Add default (5 seconds) boot wait time"
echo "timeout 5" >> "$CHROOTPATH/boot/loader/loader.conf" || exit 1
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
chroot $CHROOTPATH systemd-machine-id-setup
chroot $CHROOTPATH systemctl enable getty@tty1.service
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
echo "Welcome to the Clear Linux* ACRN SOS image!
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
Please login as root for the first time!
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
" >> $1/etc/issue
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
exit 0
2019-11-12 09:33:14 +08:00
Grant execute permission to the script:
.. code-block :: none
$ chmod a+x service-os-post.sh
2019-09-26 07:20:20 +08:00
**Scenario 2: ACRN INDUSTRY**
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
#. Create the ACRN INDUSTRY `` service-os-industry.yaml `` file:
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
$ mkdir -p ~/service-os-industry && cd ~/service-os-industry
$ vim service-os-industry.yaml
2019-09-26 07:20:20 +08:00
Update the `` service-os-industry.yaml `` file to:
2019-09-24 23:47:57 +08:00
.. code-block :: bash
:emphasize-lines: 52
block-devices: [
{name: "bdevice", file: "sos-industry.img"}
]
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
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
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
bundles: [
bootloader,
editors,
network-basic,
openssh-server,
os-core,
os-core-update,
sysadmin-basic,
systemd-networkd-autostart,
service-os
]
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
autoUpdate: false
postArchive: false
postReboot: false
telemetry: false
hostname: clr-sos
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
keyboard: us
language: en_US.UTF-8
kernel: kernel-iot-lts2018-sos
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
post-install: [
{cmd: "${yamlDir}/service-os-industry-post.sh ${chrootDir}"},
]
2019-09-26 07:20:20 +08:00
2020-01-08 16:33:21 +08:00
version: 32030
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
.. note :: Update the version value to your target Clear Linux version.
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
#. Create the `` service-os-industry-post.sh `` script:
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
$ vim service-os-industry-post.sh
2019-09-26 07:20:20 +08:00
Update the `` service-os-industry-post.sh `` script to:
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
.. code-block :: bash
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
#!/bin/bash
2019-11-12 09:33:14 +08:00
# Copyright (C) 2019 Intel Corporation.
# SPDX-License-Identifier: BSD-3-Clause
2019-09-26 07:20:20 +08:00
# ACRN SOS Image Post Install steps
set -ex
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
CHROOTPATH=$1
2019-11-12 09:33:14 +08:00
# acrn.nuc7i7dnb.industry.efi path
acrn_industry_efi_path="$CHROOTPATH/usr/lib/acrn/acrn.nuc7i7dnb.industry.efi"
2019-09-26 07:20:20 +08:00
# 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
2019-11-12 09:33:14 +08:00
Grant execute permission to the script:
.. code-block :: none
$ chmod a+x service-os-industry-post.sh
2019-09-26 07:20:20 +08:00
Step 2: Build the Service VM image
==================================
Use the clr-installer to build the Service VM image.
**Scenario 1: ACRN SDC**
.. code-block :: none
2019-09-24 23:47:57 +08:00
$ cd ~/service-os
$ sudo clr-installer -c service-os.yaml
2019-09-26 07:20:20 +08:00
2019-11-12 09:33:14 +08:00
The `` sos.img `` will be generated at current directory.
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
**Scenario 2: ACRN INDUSTRY**
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
$ cd ~/service-os-industry
$ sudo clr-installer -c service-os-industry.yaml
2019-11-12 09:33:14 +08:00
The `` sos-industry.img `` will be generated at current directory.
2019-09-26 07:20:20 +08:00
2019-08-14 14:07:43 +08:00
.. _deploy_ootb_service_vm:
2019-09-26 07:20:20 +08:00
Step 3: Deploy the Service VM image
===================================
2019-11-12 09:33:14 +08:00
#. Prepare a U disk with at least 8GB memory. Begin by formatting the U disk:
.. code-block :: none
# 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.
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
#. 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.
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
# sudo gdisk /dev/sdb
GPT fdisk (gdisk) version 1.0.3
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
Partition table scan:
MBR: protective
BSD: not present
APM: not present
GPT: present
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
Found valid GPT with protective MBR; using GPT.
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
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'
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
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'
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
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)
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
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
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
Command (? for help): w
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING
PARTITIONS!!
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
Do you want to proceed? (Y/N): Y
OK; writing new GUID partition table (GPT) to /dev/sdb.
The operation has completed successfully.
#. Download and install a bootable Clear Linux on the U disk:
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
2020-01-08 16:33:21 +08:00
$ 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
2019-09-24 23:47:57 +08:00
2019-11-12 09:33:14 +08:00
#. Copy the `` sos.img `` or `` sos-industry.img `` to the U disk:
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
$ sudo mkfs.ext4 /dev/sdb2
$ sudo mount /dev/sdb2 /mnt
2019-09-26 07:20:20 +08:00
- ACRN SDC scenario:
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
2019-11-12 09:33:14 +08:00
$ cp ~/service-os/sos.img /mnt
2019-09-24 23:47:57 +08:00
$ sync && umount /mnt
2019-09-26 07:20:20 +08:00
- ACRN INDUSTRY scenario:
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
2019-11-12 09:33:14 +08:00
$ cp ~/service-os-industry/sos-industry.img /mnt
2019-09-24 23:47:57 +08:00
$ sync && umount /mnt
2019-09-26 07:20:20 +08:00
#. Unplug the U disk from the development machine and plug it in to your test machine.
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
#. Reboot the test machine and boot from the USB.
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
#. Log in to the Live Service Clear Linux OS with your "root" account and
mount the second partition on the U disk:
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
# mount /dev/sdb2 /mnt
2019-09-26 07:20:20 +08:00
#. Format the disk that will install the Service VM image:
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
2019-09-26 11:27:18 +08:00
# sudo gdisk /dev/sda
2019-09-24 23:47:57 +08:00
GPT fdisk (gdisk) version 1.0.3
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
Partition table scan:
MBR: protective
BSD: not present
APM: not present
GPT: present
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
Found valid GPT with protective MBR; using GPT.
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
Command (? for help): o
This option deletes all partitions and creates a new protective MBR.
Proceed? (Y/N): Y
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
Command (? for help): w
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING
PARTITIONS!!
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
Do you want to proceed? (Y/N): Y
2019-09-26 11:27:18 +08:00
OK; writing new GUID partition table (GPT) to /dev/sda.
2019-09-24 23:47:57 +08:00
The operation has completed successfully.
#. Delete the old ACRN EFI firmware info:
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
# efibootmgr | grep ACRN | cut -d'*' -f1 | cut -d't' -f2 | xargs -i efibootmgr -b {} -B
#. Write the Service VM:
- ACRN SDC scenario:
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
2020-01-09 23:15:52 +08:00
# dd if=/mnt/sos.img of=/dev/sda bs=4M oflag=sync status=progress iflag=fullblock seek=0 conv=notrunc
2019-09-24 23:47:57 +08:00
- ACRN INDUSTRY scenario:
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
2020-01-09 23:15:52 +08:00
# dd if=/mnt/sos-industry.img of=/dev/sda bs=4M oflag=sync status=progress iflag=fullblock seek=0 conv=notrunc
2019-09-24 23:47:57 +08:00
2020-01-09 09:24:33 +08:00
.. note :: Given the large YAML size setting of over 100G, generating the SOS image and writing it to disk will take some time.
2019-09-24 23:47:57 +08:00
#. Configure the EFI firmware to boot the ACRN hypervisor by default:
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
2019-09-26 11:27:18 +08:00
# efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN"
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
#. Unplug the U disk and reboot the test machine. After the Clear Linux OS boots, log in as "root" for the first time.
2019-09-24 23:47:57 +08:00
.. _set_up_ootb_rtvm:
2019-09-26 07:20:20 +08:00
Generate a User VM Preempt-RT image
***** ***** ***** ***** ***** ***** *****
Step 1: Create a Preempt-RT image YAML file and script
======================================================
2019-09-24 23:47:57 +08:00
#. Create the `` preempt-rt.yaml `` file:
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
$ mkdir -p ~/preempt-rt && cd ~/preempt-rt
$ vim preempt-rt.yaml
2019-09-26 07:20:20 +08:00
Update the `` preempt-rt.yaml `` file to:
2019-09-24 23:47:57 +08:00
.. code-block :: bash
:emphasize-lines: 46
block-devices: [
{name: "bdevice", file: "preempt-rt.img"}
]
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
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
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
bundles: [
bootloader,
editors,
network-basic,
openssh-server,
os-core,
os-core-update,
sysadmin-basic,
systemd-networkd-autostart
]
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
autoUpdate: false
postArchive: false
postReboot: false
telemetry: false
hostname: clr-preempt-rt
2019-09-26 07:20:20 +08:00
2019-09-24 23:47:57 +08:00
keyboard: us
language: en_US.UTF-8
kernel: kernel-lts2018-preempt-rt
2019-09-26 07:20:20 +08:00
2020-01-08 16:33:21 +08:00
version: 32030
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
.. note :: Update the version value to your target Clear Linux version
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
Step 2: Build a User VM Preempt-RT image
========================================
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
$ sudo clr-installer -c preempt-rt.yaml
2019-09-26 07:20:20 +08:00
The `` preempt-rt.img `` will be generated at the current directory.
2019-08-14 14:07:43 +08:00
.. _deploy_ootb_rtvm:
2019-09-26 07:20:20 +08:00
Step 3: Deploy the User VM Preempt-RT image
===========================================
#. Log in to the Service VM and copy the `` preempt-rt.img `` from the development machine:
2019-09-24 23:47:57 +08:00
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
$ mkdir -p preempt-rt && cd preempt-rt
$ scp <development username>@<development machine ip>:<path to preempt-rt.img> .
#. Write `` preempt-rt.img `` to disk:
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
2019-09-26 11:27:18 +08:00
$ sudo dd if=<path to preempt-rt.img> of=/dev/nvme0n1 bs=4M oflag=sync status=progress
2019-09-24 23:47:57 +08:00
#. Launch the Preempt-RT User VM:
2019-09-26 07:20:20 +08:00
.. code-block :: none
2019-09-24 23:47:57 +08:00
2019-09-26 11:27:18 +08:00
$ sudo /usr/share/acrn/samples/nuc/launch_hard_rt_vm.sh