19. Miscellaneous

19.1. Installing additional packages

By default, it is not possible to install additional software packages (debian packages) through an Internet connection.

Caution

Please note, downloading and then using such additional packages will lead to losing support and warranty for the product!

Only for debugging or development purposes you may enable to download additional packages. For that purpose, you need to replace the file /etc/apt/source.list by /etc/apt/source.list.online.

19.2. Error (Support Information) Report

In case of errors or technical questions, you may generate an error report which will collect various system informations. This report can be sent to the acontis technical support for further investigation.

Run the following command to create the error report:

hv_gen_error_report

You may also generate such report using the System Manager tool (Help - Download Support Info).

19.3. Installing Hypervisor updates

From time to time you may get updates for the Hypervisor, for example a debian package that has to be installed or a single file that needs to be replaced. Unless such updates are not automatically installed you need to follow the specific instructions for the update.

In a production environment, it is recommended to completely disconnect the Hypervisor host from the network. This is described in Network airgapping.

If you want to update the Hypervisor over the network while the Hypervisor host is airgapped from the network, you may run a dedicated update service guest. Such guest can be temporarily executed for update purposes and be connected to the network even though the Hypervisor host is not able to access the network.

The following steps show a possible update scenario which keeps the Hypervisor host completely disconnected from the external network:

  • Stop all running applications and guests.

  • Start the update service guest. This guest must have access to the Hypervisor’s private (internal) network and mount the default SMB share: Default SMB share. This is an internal Hypervisor network share which is not exposed to the external network. Additional information about filesystem access and how to mount SMB shares can be found in Filesystem access and file sharing

  • For security reasons, you should disable this private network before connecting the service guest to the external network.

  • Download the update via the service guest and store it there.

  • For security reasons, disconnect the service guest from the external network.

  • Enable the private network to access the Hypervisor filesystem.

  • Store the update files in the Hypervisor filesystem.

  • Initiate the update installation in the ypervisor host (e.g. by creating a file on the default SMB share that triggers an update sequence in the Hypervisor host).

  • Stop the update service guest.

  • Run the update in the Hypervisor host, if necessary, reboot the system.

19.4. Virtual Memory and SWAP space

When your system runs out of physical RAM, the Linux kernel can move (or “swap”) inactive pages from memory onto disk. This mechanism helps prevent out-of-memory (OOM) errors by freeing up RAM for active tasks. However, using swap on disk is slower than using physical RAM, so it is best used as an overflow or safety net rather than a primary source of memory.

To manage swap, RTOSVisor includes a script called hv_swap_mgr. This script allows you to create, resize, remove, and query a swapfile as well as inspect existing swap partitions and memory/RAM usage. Below is an overview of its features:

  • Create or resize swapfile Use -sfs <size_in_MB> to set up a persistent swapfile. - Enforces a minimum swap size of 1GB and a maximum of total RAM. - Automatically updates /etc/fstab to ensure the swapfile is active after reboot.

  • Remove swapfile Use -sfrm to deactivate and remove the swapfile, and remove any matching entry from /etc/fstab.

  • Query swap partition Use -spq to check if there is a swap partition. If found, it displays the total size and current usage as a percentage.

  • Query swapfile Use -sfq to see how much of the swapfile (not partition) is currently used. Internally, it subtracts swap partition usage from the total system swap to isolate the file usage.

  • Query memory usage Use -mq to show an overview of system RAM usage, including total, used, free, buffer/cache, and available values (in both MB and percent).

  • Combined queries - -sq performs both partition and file swap queries. - -q performs partition and file swap queries plus a memory usage query.

By default, hv_swap_mgr uses /swapfile as the swapfile location, but you can override this by setting the environment variable SWAPFILE before running the script:

export SWAPFILE=/my/custom/swapfile
hv_swap_mgr -sfs 2048

Refer to the built-in help (-h) for detailed usage and examples.

19.5. Updating Firmware

RTOSVisor is based on thoroughly tested hardware configurations and uses stable official hardware driver versions in its distribution.

But we are not able to test every new version of every driver for every instance of new hardware.

Therefore, on the one hand, our distribution includes only official tested drivers and does not allow installing untested new versions, but on the other hand, we want to give the user the opportunity to test new hardware before the official release of its drivers.

This mechanism is made possible through the separation of hardware software into two parts: drivers and firmware. Drivers are built into the real-time kernel itself and are updated by us. And firmware, which are .bin files lying in the /lib/firmware directory, can be updated.

Please note that the use of software not tested by us is at your own risk and acontis does not guarantee the operation of new firmware. Downloading and then using such additional packages will lead to losing support and warranty for the product!

To update or install new firmware: Step 1. Please read the section “Installing additional packages” and follow the steps to activate the ability to install additional software described in this section.

Step 2. Execute script:

/hv/bin/update-firmware.sh

19.6. KVM Guests with SecureBoot

Caution

This is currently not supported!

19.6.1. UEFI and Legacy BIOS

19.6.2. UEFI

19.6.2.1. What is SecureBoot

Secure Boot is an interface between UEFI and Operating System. When SecureBoot is activated, it prevents the loading of unsigned boot loaders or drivers

Read More: https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface

19.6.2.2. Preparing keys for SecureBoot

The key thing in SecureBoot is a platform key (Platform). It establishes a relationship between a platform owner and a platform firmware. PK is a self-generated certificate owned by OEM.

Another important key is a KEK key. This key is obtained from an OS manufacturer (for ex. Microsoft) and is used to establish trust relationship between the firmware and OS.

Generating the platform key:

openssl req -newkey rsa:2048 -nodes -keyout PKpriv.key -x509 -days 365 -out PK.crt
Generating a 2048 bit RSA private key
....+++
.+++
writing new private key to 'PKpriv.key'
-----
You are about to be asked to enter information that will be incorporated into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:DE
State or Province Name (full name) [Some-State]:Bayern
Locality Name (eg, city) []:Munic
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Beer Inc
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []: BayernBeer
Email Address []:

OVMF supports keys in DER format only. So we need to convert it:

openssl x509 -in PK.crt -outform der -out PK.der

Download Key Exchange Key (KEK): MicCorKEKCA2011_2011-06-24.crt https://go.microsoft.com/fwlink/p/?linkid=321185

Download Signature Database (allows Windows to boot): MicWinProPCA2011_2011-10-19.crt https://go.microsoft.com/fwlink/?LinkId=321192

Download Microsoft signer for third party UEFI binaries via DevCenter: MicCorUEFCA2011_2011-06-27.crt https://go.microsoft.com/fwlink/p/?LinkID=321194

19.6.2.3. Building OVMF with SecureBoot support

By default, OVMF is built without SecureBoot support.

So it is recommended to fetch this project from its repository and build OVMF yourselves.

Install required packages:

sudo apt-get install build-essential git uuid-dev iasl nasm –y
sudo apt-get install iasl -y

git clone git://github.com/tianocore/edk2.git
cd edk2

Prepare build tools:

git submodule update –init
make -C BaseTools
.edksetup.sh
make -C ./BaseTools
export EDK_TOOLS_PATH=/home/rte/edk2/BaseTools
.edksetup.sh BaseTools

Edit Conf/target.txt:

ACTIVE_PLATFORM = OvmfPkg/OvmfPkgX64.dsc
TARGET_ARCH = X64
TOOL_CHAIN_TAG = GCC5

Build OVMF with SecureBoot support:

OvmfPkg/build.sh \
    -a IA32 -a X64 \
    -D SMM_REQUIRE -D SECURE_BOOT_ENABLE \
    -D FD_SIZE_2MB -D EXCLUDE_SHELL_FROM_FD

Binaries can be found in the Build directory.

19.6.2.4. Embedding SecureBoot keys to OVMF

Create a OVMF-SecureBoot directory and copy Build/OvmfX64/DEBUG_GCC5/FV/OVMF_CODE.fd and Build/OvmfX64/DEBUG_GCC5/FV/OVMF_VARS.fd to this directory.

Create an hda subdirectory and copy all generated and downloaded keys to this subdirectory.

Run qemu:

cd OVMF-SecureBoot
qemu-system-x86_64 -L . \
    -drive if=pflash,format=raw,readonly,file=OVMF_CODE.fd \
    -drive if=pflash,format=raw,file=OVMF_VARS.fd \
    -hda fat:hda \
    -net none

After booting you get to a UEFI shell. Type exit.

  1. Go to Device Manager / Secure Boot Configuration / Secure Boot Mode and change from Standard Mode to Custom Mode.

  2. PK Options / Enroll PK / Enroll PK Using File and choose PK.der

  3. KEK Options / Enroll KEK / Enroll KEK Using File and choose MicCorKEKCA2011_2011-06-24.crt

  4. DB Options / Enroll Signature / Enroll Signature Using File and choose MicWinProPCA2011_2011-10-19.crt

  5. Repeat last step and choose MicCorUEFCA2011_2011-06-27.crt

The Secure Boot Mode should be Enabled now.

Exit from BIOS, shutdown the machine.

19.7. RTOSVisor Host SecureBoot support

Caution

This is currently not supported!

It is also possible to install RTOSVisor on a host with activated Secure Boot.

To achieve this, we suggest the following steps:

  1. Deactivate Secure Boot

  2. Install RTOSVisor.iso

  3. Install the acontis certificate in UEFI

  4. Activate the acontis bootloader

  5. Activate Secure Boot

  6. Use the acontis certificate for mass production of hardware

19.7.1. Deactivating Secure Boot

It is worth noting that each computer manufacturer installs different UEFI firmware on their computers, which may result in differences in the Secure Boot activation and deactivation procedure. In this article, we will highlight general considerations using ASUS (R) UEFI BIOS Utility (TM) as an example. In other UEFI firmware, this procedure is done in a similar way.

When the computer boots, you may wish to press a hot key to enter your BIOS. In our case, this is a “Delete” key.

In BIOS, please navigate to the Boot menu and then to the “Secure Boot” menu.

Here you can see the status of Secure Boot: Disabled or Enabled. If it is enabled, we kindly request that you disable it. To do so, please navigate to the “Key Management” sub-menu and select the “Clean Secure Boot Keys” command.

Then save your changes and reboot. Secure Boot should be disabled in this case.

19.7.2. Installing RTOSVisor.iso

Install it as usual.

19.7.3. Installing the acontis certificate in UEFI

The UEFI Firmware must trust the acontis digital signature in order for the acontis boot loader to take control and run the operating system in protected mode.

To do this, add a digital certificate from Acontis to the UEFI database located in your computer’s NVRAM.

Boot into the RTOSVisor system. Select the boot menu “Configure RTOSVisor” or “Hypervisor”.

The next step is to run the sb-addkey.sh script located in the /boot/efi/EFI/acontis directory

cd /boot/efi/EFI/acontis
sudo ./sb-addkey.sh

After running the script, you will be prompted to set a password. This is needed to allow UEFI to add the acontis certificate to NVRAM after reboot. Set the password, then confirm it. After that, reboot the computer.

If everything was done correctly, after rebooting you will see a big blue screen with the title “Perform MOK management”.

Select the “Enroll MOK” menu. Then “Continue”. Then select “Yes” to the question “Enroll the key(s)?”. Then enter your password, you’ve set before. Then select “Reboot” on the next screen.

19.7.4. Activating the acontis bootloader

Before activating the acontis bootloader, please make sure the acontis certificate has been successfully added to your UEFI.

mokutil --list-enrolled

The acontis certificate must be present in the list of certificates issued by this utility.

Usually it is located in the [key 2] section.

If everything is correct, please now activate the acontis bootloader.

cd /boot/efi/EFI/acontis
sudo ./sb-activate.sh

Once activated, the bootloader acontis becomes the default bootloader on your system. UEFI then checks the bootloader’s digital signature, ensuring it is known to UEFI, and starts the bootloader. The acontis boot loader then checks the digital signature of the second-stage boot loader, acontis grub2, which is known to the acontis boot loader.

If everything is normal, acontis grub2 bootloader, digitally signed by acontis, searches for the operating system kernel from acontis. It finds it and also checks the digital signature. The acontis kernel is digitally signed by acontis, so the bootloader trusts it and starts it.

Then the OS kernel, after initializing all subsystems, starts loading numerous drivers. Each driver in the acontis distribution has also been digitally signed by acontis, so they will also be loaded. This ensures that all components are loaded securely at every stage and that no component has been tampered with or modified by a third party.

please reboot your computer after activation of the acontis bootloader.

19.7.5. Activating Secure Boot

The steps to activate Secure Boot are similar to the previous section on deactivating Secure Boot.

When the computer boots, press a hot key to enter your BIOS. In our case, this is a “Delete” key. In your case it can be F1, F5, F10 or F11 or something else.

In BIOS, please navigate to the Boot menu and then to the “Secure Boot” menu.

Here you can see the status of Secure Boot: Disabled. Then please navigate to the “Key Management” sub-menu and select the “Install Default Secure Boot Keys” command.

Every hardware vendor adds many keys to the system when installing UEFI Firmware. These are either trusted or untrusted certificates. There are several levels of keys used for this purpose: PK, KEK, DB, DBX. The “Install Default Secure Boot Keys” command loads all these default keys into NVRAM.

Then go back to “Boot->Secure Boot” menu again and make sure that the “Secure Boot state” is now “Enabled”.

Save your changes and restart your computer again.

Then select one of the boot menus, either “Configure RTOSVisor” or “Hypervisor” menu and make sure that the operating system boots successfully.

After booting, make sure that Secure Boot is indeed activated. To do this, run the command:

sudo bootctl

find the line “Secure Boot” and make sure it’s “Enabled”.

19.7.6. Use the acontis certificate for mass production of hardware

If you are a hardware manufacturer and you decide which UEFI Firmware configuration to install, or you have a contact with your hardware manufacturer who can do so, then simply ask for or add the acontis certificate to the DB database that is pre-installed with the UEFI Firmware. This will ensure that the user of your hardware does not need to go through all the steps described above. RTOSVisor can simply be installed and started using it immediately.

Location of acontis certificate in DER format: /boot/efi/EFI/acontis/cert.der

19.8. Performance Optimizations

19.8.1. KVM Guest preallocation

KVM uses the QCOW2 disk image format to store a guest system’s virtual disk as a file on the host, representing the guest’s filesystem and data. By default, KVM uses sparse allocation for QCOW2 disk images. This means that disk space is allocated dynamically as data is written, starting with a small file that grows in size only when required. While this approach is space-efficient initially, it can lead to file fragmentation over time, which may negatively impact performance, especially under heavy I/O workloads.

To address this, preallocation can be used for QCOW2 images. Preallocation reserves disk space upfront, reducing fragmentation and improving I/O performance. With full preallocation the entire disk size is allocated at creation, ensuring the best I/O performance at the cost of higher initial space usage and longer creation time.

After the initial startup of your KVM guest, the QCOW2 image is created in sparse mode by default. To convert the QCOW2 image to a fully preallocated format, stop you KVM guest and follow these steps:

# change to the path with your qcow2 file
cd /hv/VMs/windows

# create preallocated copy of your qcow2 file
qemu-img convert -O qcow2 -o preallocation=full windows.qcow2 windows.pre.qcow2

# check if the preallocated qcow2 was created without error
qemu-img info windows.pre.qcow2

# replace the existing qcow2
mv windows.pre.qcow2 windows.qcow2